stonyx 0.2.3-alpha.3 → 0.2.3-alpha.5

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/package.json

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

package/scripts/postinstall.js

@@ -1,4 +1,8 @@
-import { copyFile, createDirectory } from '@stonyx/utils/file';
+// Skip postinstall for global installations
+const isGlobal = !process.env.INIT_CWD || process.env.npm_config_global === 'true';
+if (isGlobal) process.exit(0);
+
+const { copyFile, createDirectory } = await import('@stonyx/utils/file');
 
 const projectDir = process.env.INIT_CWD;
 const configDir = `${projectDir}/config`;

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']
   }
 ];