zyket 1.1.5 → 1.1.7

package/.claude-plugin/marketplace.json

@@ -1,16 +1,17 @@
 {
-  "name": "zyket",
+  "name": "zyket-plugins",
   "owner": {
-    "name": "PemaK"
+    "name": "OnchainTech"
   },
   "metadata": {
-    "description": "A collection of Claude plugins for building Zyket apps",
-    "version": "1.0.8"
+    "description": "Official Claude Code plugins for the Zyket framework"
   },
   "plugins": [
     {
       "name": "zyket",
-      "source": "./claude-plugin"
+      "source": "./plugin",
+      "description": "Generate Zyket framework components — handlers, guards, routes, middlewares, services, events, schedulers, workers, and extensions.",
+      "version": "1.0.0"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zyket",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"

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

@@ -0,0 +1,8 @@
+{
+  "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",
+  "author": {
+    "name": "OnchainTech"
+  }
+}

package/plugin/skills/generate/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: generate
+description: Generate Zyket framework components — handlers, guards, routes, middlewares, services, events, schedulers, workers, and extensions. Use when the user wants to create or scaffold any Zyket component.
+allowed-tools: Read, Write, Grep, Glob, Bash
+argument-hint: [component-type] [name]
+---
+
+# Zyket Component Generator
+
+Generate a **$ARGUMENTS** component for the Zyket framework.
+
+## Instructions
+
+1. Parse `$ARGUMENTS` — first word is the component type, remaining words form the name.
+2. Read the matching component reference from [components/](components/) to get the exact pattern.
+3. Read the [rules.md](rules.md) file for conventions that apply to all components.
+4. Before writing, read the actual base class from the project's `node_modules/zyket/` or framework source to confirm the API hasn't changed.
+5. Create the target directory if it doesn't exist.
+6. Write the component file following the reference pattern exactly.
+
+## Component Types
+
+| Type | Reference | Location |
+|------|-----------|----------|
+| `handler` | [components/handler.md](components/handler.md) | `src/handlers/<name>.js` |
+| `guard` | [components/guard.md](components/guard.md) | `src/guards/<name>.js` |
+| `route` | [components/route.md](components/route.md) | `src/routes/<path>.js` |
+| `middleware` | [components/middleware.md](components/middleware.md) | `src/middlewares/<name>.js` |
+| `service` | [components/service.md](components/service.md) | Custom location |
+| `event` | [components/event.md](components/event.md) | `src/events/<name>.js` |
+| `scheduler` | [components/scheduler.md](components/scheduler.md) | `src/schedulers/<name>.js` |
+| `worker` | [components/worker.md](components/worker.md) | `src/workers/<name>.js` |
+| `extension` | [components/extension.md](components/extension.md) | Custom location |

package/plugin/skills/generate/components/event.md

@@ -0,0 +1,47 @@
+# Event
+
+Internal event handler. Enables decoupled pub/sub communication between components.
+
+## Location
+
+`src/events/<name>.js` — the filename becomes the **event name**.
+
+## Base Class
+
+`Event` from `zyket`
+
+## Template
+
+```js
+const { Event } = require("zyket");
+
+module.exports = class extends Event {
+  async handle({ container, payload }) {
+    // Process the event payload
+  }
+}
+```
+
+## Method Signature
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `container` | `ContainerBuilder` | DI service container |
+| `payload` | `any` | Data passed when the event was emitted |
+
+## Emitting Events
+
+From any component with container access:
+
+```js
+// Synchronous-style (still returns promise)
+container.get('events').emit('event-name', { key: "value" });
+
+// Async with timeout (default 30s)
+await container.get('events').emitAsync('event-name', { key: "value" }, 15000);
+```
+
+## Requirements
+
+- The `events` service must be enabled (`DISABLE_EVENTS` must not be `true`).
+- The event name used in `emit()` must match a filename in `src/events/`.

package/plugin/skills/generate/components/extension.md

@@ -0,0 +1,78 @@
+# Extension
+
+Post-boot plugin with full container access. Integrates with booted services to add features like dashboards, file browsers, or third-party integrations.
+
+## Location
+
+No fixed location — extensions are manually registered in the Kernel constructor.
+
+## Base Class
+
+`Extension` from `zyket`
+
+## Template
+
+```js
+const { Extension } = require("zyket");
+
+module.exports = class MyExtension extends Extension {
+  constructor(options = {}) {
+    super("MyExtension"); // extension display name
+    // Store any configuration options
+  }
+
+  async load(container) {
+    // Runs after all services have booted
+    // Full access to every service via container
+  }
+}
+```
+
+## Registration
+
+```js
+const { Kernel } = require("zyket");
+const MyExtension = require("./extensions/MyExtension");
+
+const kernel = new Kernel({
+  extensions: [new MyExtension({ path: "/my-ext" })]
+});
+```
+
+## Method Signature
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `container` | `ContainerBuilder` | DI service container with all booted services |
+
+## Common Patterns
+
+### Registering additional routes
+
+```js
+async load(container) {
+  const express = container.get('express');
+  express.registerRoutes([new MyRoute("/custom-path")]);
+}
+```
+
+### Registering a raw Express handler
+
+```js
+async load(container) {
+  const express = container.get('express');
+  express.regiterRawAllRoutes("/webhook", (req, res) => {
+    res.send("OK");
+  });
+}
+```
+
+### Checking service availability
+
+```js
+async load(container) {
+  if (!container.has('s3')) {
+    return container.get('logger').warn('MyExtension: s3 service not found, skipping');
+  }
+}
+```

package/plugin/skills/generate/components/guard.md

@@ -0,0 +1,44 @@
+# Guard
+
+Socket.IO guard. Protects handlers and connections by running validation logic before they execute.
+
+## Location
+
+`src/guards/<name>.js` — the filename becomes the **guard name** referenced in handlers.
+
+## Base Class
+
+`Guard` from `zyket`
+
+## Template
+
+```js
+const { Guard } = require("zyket");
+
+module.exports = class extends Guard {
+  async handle({ container, socket, io }) {
+    // Throw an error to block the event or connection
+    // If this method completes without throwing, the guard passes
+  }
+}
+```
+
+## Method Signature
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `container` | `ContainerBuilder` | DI service container |
+| `socket` | `Socket` | The connected socket |
+| `io` | `Server` | Socket.IO server instance |
+
+## Usage
+
+Reference guards by filename (without `.js`) in a handler's `guards` array:
+
+```js
+// src/handlers/send-message.js
+module.exports = class extends Handler {
+  guards = ["auth"]; // references src/guards/auth.js
+  async handle({ container, socket, data, io }) { }
+}
+```

package/plugin/skills/generate/components/handler.md

@@ -0,0 +1,48 @@
+# Handler
+
+Socket.IO event handler. Receives and responds to real-time WebSocket events.
+
+## Location
+
+`src/handlers/<name>.js` — the filename becomes the **event name** the client emits.
+
+The special file `src/handlers/connection.js` runs when a new socket connects.
+
+## Base Class
+
+`Handler` from `zyket`
+
+## Template
+
+```js
+const { Handler } = require("zyket");
+
+module.exports = class extends Handler {
+  // Optional: guard names that must pass before this handler runs
+  // guards = ["auth"];
+
+  async handle({ container, socket, data, io }) {
+    // data — payload sent by the client
+    // socket — the connected socket instance
+    // io — the Socket.IO server instance
+    // Return value is sent back via callback if the client provided one
+  }
+}
+```
+
+## Method Signature
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `container` | `ContainerBuilder` | DI service container |
+| `socket` | `Socket` | The connected socket |
+| `data` | `any` | Payload from the client |
+| `io` | `Server` | Socket.IO server instance |
+
+## Guards
+
+Set `guards` as an array of guard filenames (without `.js`). Guards run in order before the handler. If a guard throws, the handler is skipped and the error is returned to the client callback.
+
+```js
+guards = ["auth", "rate-limit"];
+```

package/plugin/skills/generate/components/middleware.md

@@ -0,0 +1,52 @@
+# Middleware
+
+HTTP middleware. Runs before route handlers to validate, transform, or block requests.
+
+## Location
+
+`src/middlewares/<name>.js`
+
+Middlewares are **not auto-discovered**. They must be imported and attached to routes manually.
+
+## Base Class
+
+`Middleware` from `zyket`
+
+## Template
+
+```js
+const { Middleware } = require("zyket");
+
+module.exports = class extends Middleware {
+  handle({ container, request, response, next }) {
+    // Call next() to pass control to the next middleware or route handler
+    // Or respond directly to block the request
+    next();
+  }
+}
+```
+
+## Method Signature
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `container` | `ContainerBuilder` | DI service container |
+| `request` | `Request` | Express request object |
+| `response` | `Response` | Express response object |
+| `next` | `Function` | Call to continue the chain |
+
+## Usage in Routes
+
+```js
+const { Route } = require("zyket");
+const AuthMiddleware = require("../middlewares/auth");
+
+module.exports = class extends Route {
+  middlewares = {
+    get: [new AuthMiddleware()],
+    post: [new AuthMiddleware()]
+  }
+
+  async get({ container, request }) { }
+}
+```

package/plugin/skills/generate/components/route.md

@@ -0,0 +1,62 @@
+# Route
+
+HTTP endpoint. Handles REST API requests via Express.
+
+## Location
+
+`src/routes/<path>.js` — the file path maps to the **URL path**:
+
+| File | URL |
+|------|-----|
+| `src/routes/index.js` | `/` |
+| `src/routes/users.js` | `/users` |
+| `src/routes/users/[id].js` | `/users/:id` |
+| `src/routes/auth/login.js` | `/auth/login` |
+
+- `index.js` maps to the parent directory path
+- `[param]` in filenames becomes `:param` in the URL
+- Nested folders create nested URL segments
+
+## Base Class
+
+`Route` from `zyket`
+
+## Template
+
+```js
+const { Route } = require("zyket");
+
+module.exports = class extends Route {
+  // Optional: attach middlewares per HTTP method
+  // middlewares = {
+  //   get: [new SomeMiddleware()],
+  //   post: [new SomeMiddleware()]
+  // }
+
+  async get({ container, request, response }) {
+    return { data: "value" };
+  }
+
+  async post({ container, request, response }) {
+    const body = request.body;
+    return { status: 201, created: true };
+  }
+
+  // Also available: put, delete
+}
+```
+
+## Method Signature
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `container` | `ContainerBuilder` | DI service container |
+| `request` | `Request` | Express request object |
+| `response` | `Response` | Express response object |
+
+## Return Values
+
+- Return an **object** — the framework wraps it with `{ success: true, ...returnValue }` and sends as JSON.
+- Set a `status` key to change the HTTP status code (defaults to `200`).
+- Return a `RedirectResponse` to redirect: `return new RedirectResponse("/target-url")`.
+- Return a `Buffer` to send a file download.

package/plugin/skills/generate/components/scheduler.md

@@ -0,0 +1,60 @@
+# Scheduler
+
+Cron job. Runs tasks on a recurring schedule using cron expressions.
+
+## Location
+
+`src/schedulers/<name>.js` — the filename becomes the **scheduler name**.
+
+## Base Class
+
+`Schedule` from `zyket`
+
+## Template
+
+```js
+const { Schedule } = require("zyket");
+
+module.exports = class extends Schedule {
+  time = "*/5 * * * *"; // required: cron expression
+
+  async handle({ container }) {
+    // Runs on the cron schedule
+  }
+}
+```
+
+## Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `time` | `string` | Yes | Cron expression defining the schedule |
+
+## Method Signature
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `container` | `ContainerBuilder` | DI service container |
+
+## Cron Expression Reference
+
+```
+┌────────── minute (0-59)
+│ ┌──────── hour (0-23)
+│ │ ┌────── day of month (1-31)
+│ │ │ ┌──── month (1-12)
+│ │ │ │ ┌── day of week (0-7, 0 and 7 = Sunday)
+│ │ │ │ │
+* * * * *
+```
+
+| Expression | Meaning |
+|------------|---------|
+| `*/5 * * * *` | Every 5 minutes |
+| `0 * * * *` | Every hour |
+| `0 0 * * *` | Daily at midnight |
+| `0 2 * * 0` | Sundays at 2 AM |
+
+## Requirements
+
+- The `scheduler` service must be enabled (`DISABLE_SCHEDULER` must not be `true`).

package/plugin/skills/generate/components/service.md

@@ -0,0 +1,66 @@
+# Service
+
+Custom service with dependency injection. Long-running components that provide shared functionality across the application.
+
+## Location
+
+No fixed location — services are manually registered in the Kernel constructor.
+
+## Base Class
+
+`Service` from `zyket`
+
+## Template
+
+```js
+const { Service } = require("zyket");
+
+module.exports = class MyService extends Service {
+  #container;
+
+  constructor(container) {
+    super("my-service"); // name used with container.get()
+    this.#container = container;
+  }
+
+  async boot({ httpServer } = {}) {
+    // Called during kernel boot
+    // Initialize connections, load config, set up state
+  }
+
+  // Public API methods
+}
+```
+
+## Registration
+
+Services are registered in the Kernel constructor as a tuple: `[name, class, args]`.
+
+```js
+const { Kernel } = require("zyket");
+const MyService = require("./services/MyService");
+
+const kernel = new Kernel({
+  services: [
+    ["my-service", MyService, ["@service_container"]]
+  ]
+});
+```
+
+## Special Arguments
+
+| Placeholder | Replaced With |
+|------------|---------------|
+| `"@service_container"` | The DI `ContainerBuilder` instance |
+
+## Boot Signature
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `httpServer` | `http.Server` | The underlying HTTP server |
+
+## Accessing From Other Components
+
+```js
+const myService = container.get("my-service");
+```

package/plugin/skills/generate/components/worker.md

@@ -0,0 +1,53 @@
+# Worker
+
+BullMQ job processor. Processes background jobs from a named queue.
+
+## Location
+
+`src/workers/<name>.js` — the filename becomes the **worker name**.
+
+## Base Class
+
+`Worker` from `zyket`
+
+## Template
+
+```js
+const { Worker } = require("zyket");
+
+module.exports = class extends Worker {
+  queueName = "my-queue"; // required: must match a queue in QUEUES env var
+
+  async handle({ container, job }) {
+    // job.data contains the job payload
+  }
+}
+```
+
+## Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `queueName` | `string` | Yes | Name of the BullMQ queue to process |
+
+## Method Signature
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `container` | `ContainerBuilder` | DI service container |
+| `job` | `Job` | BullMQ job instance |
+
+## Adding Jobs to a Queue
+
+From any component with container access:
+
+```js
+const bull = container.get('bullmq');
+await bull.queues['my-queue'].add('job-name', { key: "value" });
+```
+
+## Requirements
+
+- `CACHE_URL` environment variable must be set (Redis connection).
+- `QUEUES` environment variable must include the queue name.
+- `DISABLE_BULLMQ` must not be `true`.

package/plugin/skills/generate/rules.md

@@ -0,0 +1,29 @@
+# Zyket Generation Rules
+
+These rules apply to **all** generated components.
+
+## Module System
+
+- Always use `module.exports =` — Zyket uses `require()` and validates with `prototype instanceof BaseClass`.
+- Always import base classes from `zyket`: `const { Handler } = require("zyket");`
+
+## Auto-Discovery
+
+Handlers, guards, routes, events, schedulers, and workers are **auto-discovered** by the framework.
+- The **filename** becomes the component's identity (event name, guard name, route path, etc.).
+- Use **kebab-case** for filenames.
+- Do **not** add constructor parameters to auto-discovered components — they receive only their name (derived from filename) via the base class constructor.
+
+## Dependency Injection
+
+- All component methods receive `{ container }` as part of their arguments.
+- Access services via `container.get('service-name')`.
+- Available default services: `logger`, `database`, `cache`, `s3`, `events`, `scheduler`, `bullmq`, `socketio`, `express`.
+- Service availability depends on environment variables — check before using.
+
+## Code Style
+
+- Keep components focused — one responsibility per file.
+- Don't add guards or middlewares unless the user explicitly asks for them.
+- Don't add error handling that duplicates what the framework already provides.
+- Don't add comments explaining obvious code.

package/.claude/settings.json

@@ -1,3 +0,0 @@
-{
-  "enabledPlugins": {}
-}

package/claude-plugin/.claude-plugin/commands/event.md

@@ -1,29 +0,0 @@
-# Create a Zyket Event
-
-Create a new event file in the Zyket project.
-
-## Instructions
-
-Events live in `src/events/`. The filename (without `.js`) is the event name used in `emit()`.
-
-### Template
-
-```js
-const { Event } = require("zyket");
-
-module.exports = class $EventName$Event extends Event {
-  async handle({ container, payload }) {
-    container.get("logger").info("$EventName$ event fired", payload);
-    // Your event logic here
-  }
-};
-```
-
-### Steps:
-1. Create `src/events/$event-name$.js`.
-2. Implement the handler logic based on the user's description.
-3. Show the user how to emit it:
-   ```js
-   container.get("events").emitAsync("$event-name$", { ...payload });
-   ```
-4. Remind the user to set `DISABLE_EVENTS=false` in `.env`.

package/claude-plugin/.claude-plugin/commands/guard.md

@@ -1,37 +0,0 @@
-# Create a Zyket Socket.IO Guard
-
-Create a new Socket.IO guard file in the Zyket project.
-
-## Instructions
-
-Guards live in `src/guards/`. The filename (without `.js`) is the guard name used in handler `guards` arrays. Guards run before an event handler or connection and can block execution by throwing an error.
-
-### Template
-
-```js
-const { Guard } = require("zyket");
-
-module.exports = class $Name$Guard extends Guard {
-  async handle({ container, socket, io }) {
-    // Validate / authorize the socket
-    // Throw an error to block the event or connection
-    // e.g.:
-    const token = socket.handshake.auth?.token;
-    if (!token) throw new Error("Unauthorized");
-
-    // Attach data to socket for handlers to use
-    // socket.data.user = verifiedUser;
-  }
-};
-```
-
-### Steps:
-1. Create `src/guards/$name$.js`.
-2. Implement the authorization logic.
-3. Show how to attach it to a handler:
-   ```js
-   module.exports = class MyHandler extends Handler {
-     guards = ["$name$"];
-     // ...
-   };
-   ```