stonyx 0.2.3-alpha.2 → 0.2.3-alpha.4

package/.claude/index.md

@@ -1,5 +1,7 @@
 # Stonyx CLI Guide
 
+See [docs/index.md](../docs/index.md) for full documentation including conventions, modules, lifecycle, and API reference.
+
 ## Installation
 
 Stonyx is the core framework package. The CLI is provided by the `stonyx` binary defined in `package.json`.

package/docs/conventions/discord-conventions.md

@@ -0,0 +1,62 @@
+# Discord Conventions
+
+Conventions for projects using `@stonyx/discord`.
+
+## Command Files
+
+- One class per file in the configured command directory (default: `discord-commands/`)
+- Each file default-exports a class extending `Command` from `@stonyx/discord`
+- Class must define a `data` property (a `SlashCommandBuilder` instance) and an `async execute(interaction)` method
+- Class ordering: static properties → `data` → `execute()`
+- Filenames use kebab-case; `forEachFileImport` converts to camelCase for internal registration
+- Permission checks belong in the consuming application, not in the module
+
+```js
+import { Command } from '@stonyx/discord';
+import { SlashCommandBuilder } from 'discord.js';
+
+export default class PingCommand extends Command {
+  data = new SlashCommandBuilder()
+    .setName('ping')
+    .setDescription('Replies with Pong!');
+
+  async execute(interaction) {
+    await interaction.reply('Pong!');
+  }
+}
+```
+
+## Event Handler Files
+
+- One class per file in the configured event directory (default: `discord-events/`)
+- Each file default-exports a class extending `EventHandler` from `@stonyx/discord`
+- Class must set `static event` to a valid Discord.js event name (e.g., `'messageCreate'`, `'voiceStateUpdate'`)
+- Class must implement a `handle(...args)` method matching the Discord.js event signature
+- Class ordering: static properties → `handle()`
+
+```js
+import { EventHandler } from '@stonyx/discord';
+
+export default class WelcomeHandler extends EventHandler {
+  static event = 'guildMemberAdd';
+
+  handle(member) {
+    // Welcome new member
+  }
+}
+```
+
+## Configuration
+
+- Config namespace: `config.discord`
+- Environment variables prefixed with `DISCORD_`
+- Logging: `log.discord()` — configured via `logColor: '#7289da'` and `logMethod: 'discord'`
+- Intent auto-derivation: the module computes required gateway intents from discovered event handlers; use `additionalIntents` in config for edge cases
+
+## Module Keywords
+
+```json
+"keywords": ["stonyx-async", "stonyx-module"]
+```
+
+`stonyx-async` indicates the module's `init()` is async and must be awaited by the framework.

package/docs/conventions/framework-modules.md

@@ -103,6 +103,12 @@ WebSocket handlers. Class ordering: static properties → `server()` method →
 
 Exports: `SocketServer`, `SocketClient`, `Handler`, `Sockets`
 
+## `@stonyx/discord`
+
+Discord bot with command and event handler auto-discovery. Class ordering: static properties → `data` / `static event` → `execute()` / `handle()`.
+
+Exports: `DiscordBot`, `Command`, `EventHandler`, `Discord`, `chunkMessage`
+
 ## `@stonyx/oauth`
 
 OAuth providers. Class ordering: constructor with `super()` → async methods → transform methods.

package/docs/conventions/index.md

@@ -20,4 +20,5 @@ Universal rules that apply to every Stonyx project. Section-specific conventions
 - [Framework Modules](./framework-modules.md) — when to use which `@stonyx/*` module
 - [ORM Conventions](./orm-conventions.md) — models, serializers, access control, transforms, hooks
 - [REST Conventions](./rest-conventions.md) — REST server request classes and handlers
+- [Discord Conventions](./discord-conventions.md) — Discord bot commands and event handlers
 - [Testing Conventions](./testing-conventions.md) — test organization, patterns, and tooling

package/docs/conventions/project-structure.md

@@ -40,8 +40,7 @@ Flat file structure at root level — non-directory project files live at the pr
 | `requests/` | REST request handlers | When using `@stonyx/rest-server` |
 | `crons/` | Scheduled tasks | When using `@stonyx/cron` |
 | `clients/` | External API clients | When fetching external data |
-| `resources/` | Business logic resources | As needed |
-| `test/` | Tests | Always |
+| `test/`| Tests | Always |
 | `utils.js` or `utils/` | Project-specific reusable logic | As needed (never duplicate `@stonyx/utils`) |
 
 ### Nested Model Directories

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stonyx",
-  "version": "0.2.3-alpha.2",
+  "version": "0.2.3-alpha.4",
   "description": "Base stonyx framework module",
   "main": "main.js",
   "type": "module",

package/src/cli/new.js

@@ -33,6 +33,11 @@ const MODULE_OPTIONS = [
   {
     question: 'Will this project need pub/sub events?',
     package: '@stonyx/events'
+  },
+  {
+    question: 'Will this project need a Discord bot?',
+    package: '@stonyx/discord',
+    dirs: ['discord-commands', 'discord-events']
   }
 ];