@stonyx/discord 0.1.0

package/.claude/architecture.md

@@ -0,0 +1,124 @@
+# Architecture
+
+## Module Structure
+
+```
+stonyx-discord/
+├── config/environment.js      # Default config, env var overrides
+├── src/
+│   ├── main.js                # Discord class (Stonyx entry) + barrel exports
+│   ├── bot.js                 # DiscordBot singleton — core logic
+│   ├── command.js             # Base Command class
+│   ├── event-handler.js       # Base EventHandler class
+│   ├── intents.js             # Intent/partial auto-derivation
+│   └── message.js             # Message chunking utility
+└── test/
+    ├── config/environment.js  # Test config overrides
+    ├── sample/                # Sample commands and event handlers
+    └── unit/                  # Unit tests
+```
+
+## Stonyx Integration
+
+### Auto-Initialization
+
+The package declares `stonyx-async` + `stonyx-module` keywords. When Stonyx starts:
+
+1. Reads `config/environment.js` and merges into `config.discord`
+2. Registers `log.discord()` via `logColor: '#7289da'` + `logMethod: 'discord'`
+3. Imports `src/main.js`, instantiates the default `Discord` class, calls `.init()`
+4. `Discord.init()` creates a `DiscordBot` instance and calls `bot.init()`
+
+### Standalone Mode (Testing)
+
+When running `stonyx test` from within the package directory, Stonyx detects the `stonyx-` prefix in the path and transforms the config:
+
+```javascript
+// config/environment.js exports { token, botUserId, serverId, ... }
+// Stonyx wraps it as: { discord: { token, botUserId, serverId, ... } }
+```
+
+Test overrides from `test/config/environment.js` are merged on top.
+
+## Singleton Pattern
+
+Both `Discord` (entry point) and `DiscordBot` use the Stonyx singleton convention:
+
+```javascript
+constructor() {
+  if (DiscordBot.instance) return DiscordBot.instance;
+  DiscordBot.instance = this;
+}
+```
+
+`reset()` sets the static instance back to `null` and clears internal state (used in tests).
+
+## Lazy Initialization Flow
+
+`DiscordBot.init()` implements a lazy start — the bot only connects if there is work to do:
+
+```
+init()
+  ├── No token? → log warning, resolve ready, return (no bot started)
+  ├── discoverCommands() → scan commandDir
+  ├── discoverEvents() → scan eventDir
+  ├── No commands AND no events? → log warning, resolve ready, return
+  └── Has work:
+      ├── deriveIntents(eventHandlers, additionalIntents)
+      ├── derivePartials(intents, additionalPartials)
+      ├── If commands exist → add Guilds intent
+      ├── Create discord.js Client with deduped intents + partials
+      ├── registerClientEvents() → wire interactionCreate + event handlers
+      ├── client.login(token)
+      └── await ready (resolves on 'clientReady' event)
+```
+
+The `ready` property is a Promise created in the constructor. It resolves either when the bot connects or when init determines there is nothing to do.
+
+## Handler Discovery Lifecycle
+
+### Command Discovery
+
+```javascript
+await forEachFileImport(commandDir, (CommandClass, { name }) => {
+  const instance = new CommandClass();
+  // Validate: must have data (SlashCommandBuilder) and execute function
+  instance._bot = this;
+  this.commands[instance.data.name] = instance;
+}, { ignoreAccessFailure: true });
+```
+
+- Commands are keyed by `instance.data.name` (the slash command name), not the filename
+- `ignoreAccessFailure: true` means a missing directory is silently ignored
+
+### Event Handler Discovery
+
+```javascript
+await forEachFileImport(eventDir, (EventHandlerClass, { name }) => {
+  // Validate: must have static event property
+  const instance = new EventHandlerClass();
+  instance._bot = this;
+  this.eventHandlers.push(instance);
+}, { ignoreAccessFailure: true });
+```
+
+- Event handlers are stored in an array (not keyed), since multiple handlers could share an event name
+- Each handler is wired to the client after discovery: `client.on(handler.constructor.event, (...args) => handler.handle(...args))`
+
+## Client Event Wiring
+
+`registerClientEvents()` sets up three things on the discord.js `Client`:
+
+1. **`clientReady`** — resolves the `ready` promise and logs
+2. **`interactionCreate`** — routes slash commands to the matching `Command.execute()`, with error handling
+3. **Event handlers** — iterates `this.eventHandlers` and binds each to its event via `client.on()`
+
+## Dependency Graph
+
+| Package | Purpose |
+|---------|---------|
+| `discord.js` | Discord API client — `Client`, `GatewayIntentBits`, `SlashCommandBuilder`, etc. |
+| `stonyx` | Framework core — config, logging, module lifecycle |
+| `@stonyx/utils` (dev) | `forEachFileImport` for handler auto-discovery |
+| `qunit` (dev) | Test framework |
+| `sinon` (dev) | Stubs and spies for unit tests |

package/.claude/commands.md

@@ -0,0 +1,122 @@
+# Commands
+
+## Overview
+
+Commands are slash commands registered with Discord. Each command is a class that extends `Command`, defines a `data` property (a `SlashCommandBuilder`), and implements an `execute(interaction)` method. Command files live in the command directory (default: `./discord-commands`).
+
+## Base Class
+
+```javascript
+// src/command.js
+export default class Command {
+  static skipAuth = false;
+}
+```
+
+The base class provides the `skipAuth` default and a common prototype. The `skipAuth` property is reserved for future auth gating.
+
+## Defining a Command
+
+```javascript
+import { SlashCommandBuilder } from 'discord.js';
+import { Command } from '@stonyx/discord';
+
+export default class PingCommand extends Command {
+  data = new SlashCommandBuilder()
+    .setName('ping')
+    .setDescription('Replies with Pong!');
+
+  async execute(interaction) {
+    await interaction.reply('Pong!');
+  }
+}
+```
+
+### Required properties
+
+- **`data`** — a `SlashCommandBuilder` instance. The `name` set here is what users type as `/name`
+- **`execute(interaction)`** — receives the Discord.js `ChatInputCommandInteraction`. Must be a function
+
+### Available context
+
+- **`this._bot`** — reference to the `DiscordBot` instance, set automatically during discovery. Use it to access utility methods like `this._bot.reply()`, `this._bot.sendMessage()`, etc.
+
+## Command Discovery
+
+On `DiscordBot.init()`, commands are discovered via `forEachFileImport`:
+
+```javascript
+await forEachFileImport(commandDir, (CommandClass, { name }) => {
+  const instance = new CommandClass();
+
+  if (!instance.data || typeof instance.execute !== 'function') {
+    log.discord(`Command "${name}" is missing data or execute — skipping`);
+    return;
+  }
+
+  instance._bot = this;
+  this.commands[instance.data.name] = instance;
+  log.discord(`Loaded command: /${instance.data.name}`);
+}, { ignoreAccessFailure: true });
+```
+
+Key details:
+
+- **Registration key:** Commands are stored by `instance.data.name` (the slash command name), not the filename
+- **Filename convention:** kebab-case files (`ping-stats.js`) are converted to camelCase (`pingStats`) by `forEachFileImport`, but the command name comes from `data.name`
+- **Missing directory:** `ignoreAccessFailure: true` means if the command directory doesn't exist, no error is thrown
+- **Validation:** Commands missing `data` or `execute` are logged and skipped
+
+## SlashCommandBuilder Usage
+
+Commands use the discord.js `SlashCommandBuilder` API:
+
+```javascript
+import { SlashCommandBuilder } from 'discord.js';
+
+// Simple command
+data = new SlashCommandBuilder()
+  .setName('ping')
+  .setDescription('Check if the bot is alive');
+
+// Command with options
+data = new SlashCommandBuilder()
+  .setName('roll')
+  .setDescription('Roll dice')
+  .addIntegerOption(option =>
+    option.setName('sides')
+      .setDescription('Number of sides')
+      .setRequired(true)
+  );
+```
+
+## Interaction Handling
+
+When a user runs a slash command, the framework's `interactionCreate` listener:
+
+1. Checks `interaction.isChatInputCommand()` — ignores non-command interactions
+2. Looks up `this.commands[commandName]`
+3. If not found → replies with ephemeral "not available" message
+4. Calls `command.execute(interaction)` wrapped in try/catch
+5. On error → logs via `log.error()`, sends ephemeral error reply (uses `followUp` if already replied/deferred)
+
+## skipAuth Property
+
+`static skipAuth = false` is defined on the base `Command` class. This property is reserved for future use — it does not currently gate execution. All commands are executed if they are registered.
+
+## Using Bot Utilities in Commands
+
+Access the bot instance via `this._bot`:
+
+```javascript
+export default class StatusCommand extends Command {
+  data = new SlashCommandBuilder()
+    .setName('status')
+    .setDescription('Show bot status');
+
+  async execute(interaction) {
+    const guild = await this._bot.getGuild();
+    await this._bot.reply(interaction, `Serving ${guild.memberCount} members`);
+  }
+}
+```

package/.claude/configuration.md

@@ -0,0 +1,126 @@
+# Configuration
+
+## How Config Loads
+
+The package provides `config/environment.js` with defaults. Stonyx merges this into `config.discord`:
+
+1. Stonyx reads `config/environment.js` (the raw export)
+2. Wraps it under the `discord` key (derived from package name `@stonyx/discord` -> `discord`)
+3. Merges any user overrides from the consumer app's environment config
+4. In test mode, merges `test/config/environment.js` on top
+
+Access in code: `import config from 'stonyx/config'` -> `config.discord.token`, etc.
+
+## Config Options
+
+| Key | Env Var | Default | Type | Description |
+|-----|---------|---------|------|-------------|
+| `token` | `DISCORD_TOKEN` | `''` | String | Discord bot token. If empty, bot will not start |
+| `botUserId` | `DISCORD_BOT_USER_ID` | `''` | String | The bot's Discord user ID |
+| `serverId` | `DISCORD_SERVER_ID` | `''` | String | Default guild/server ID (used by `getGuild()`, `giveRole()`) |
+| `commandDir` | `DISCORD_COMMAND_DIR` | `'./discord-commands'` | String | Path to command files directory |
+| `eventDir` | `DISCORD_EVENT_DIR` | `'./discord-events'` | String | Path to event handler files directory |
+| `maxMessagesPerRequest` | `DISCORD_MAX_MESSAGES_PER_REQUEST` | `100` | Number | Max messages fetched per `getChannelMessages()` call |
+| `additionalIntents` | — | `[]` | Array | Extra intent names to include beyond auto-derived ones |
+| `additionalPartials` | — | `[]` | Array | Extra partial names to include beyond auto-derived ones |
+
+### Logging config (framework-internal)
+
+| Key | Value | Purpose |
+|-----|-------|---------|
+| `log` | `DISCORD_LOG` / `false` | Enable verbose logging |
+| `logColor` | `'#7289da'` | Chronicle log color for `log.discord()` |
+| `logMethod` | `'discord'` | Creates `log.discord()` method |
+
+## Default Config File
+
+```javascript
+// config/environment.js
+const {
+  DISCORD_TOKEN,
+  DISCORD_BOT_USER_ID,
+  DISCORD_SERVER_ID,
+  DISCORD_COMMAND_DIR,
+  DISCORD_EVENT_DIR,
+  DISCORD_MAX_MESSAGES_PER_REQUEST,
+  DISCORD_LOG,
+} = process.env;
+
+export default {
+  token: DISCORD_TOKEN ?? '',
+  botUserId: DISCORD_BOT_USER_ID ?? '',
+  serverId: DISCORD_SERVER_ID ?? '',
+  commandDir: DISCORD_COMMAND_DIR ?? './discord-commands',
+  eventDir: DISCORD_EVENT_DIR ?? './discord-events',
+  maxMessagesPerRequest: DISCORD_MAX_MESSAGES_PER_REQUEST ?? 100,
+  additionalIntents: [],
+  additionalPartials: [],
+  log: DISCORD_LOG ?? false,
+  logColor: '#7289da',
+  logMethod: 'discord',
+};
+```
+
+## Intent Auto-Derivation Details
+
+Intents are computed automatically from registered event handlers. The process:
+
+1. Start with an empty set
+2. For each event handler, look up the event name in `EVENT_INTENT_MAP` (in `src/intents.js`)
+3. Add all mapped intents to the set
+4. Add any intents from `config.discord.additionalIntents` (resolved against `GatewayIntentBits` enum)
+5. If commands are registered, add `GatewayIntentBits.Guilds`
+6. Deduplicate and pass to the discord.js `Client`
+
+### additionalIntents
+
+An array of `GatewayIntentBits` key names (strings). These are resolved at runtime:
+
+```javascript
+for (const name of additionalIntents) {
+  const intent = GatewayIntentBits[name];
+  if (intent !== undefined) intents.add(intent);
+}
+```
+
+Valid values include: `Guilds`, `GuildMembers`, `GuildMessages`, `GuildPresences`, `DirectMessages`, `MessageContent`, `GuildVoiceStates`, `GuildInvites`, etc.
+
+### additionalPartials
+
+Same pattern — an array of `Partials` key names (strings). Resolved against the discord.js `Partials` enum.
+
+Valid values include: `Channel`, `Message`, `Reaction`, `User`, `GuildMember`, `ThreadMember`, etc.
+
+## Consumer Override Example
+
+In a consumer app's `config/environment.js`:
+
+```javascript
+export default {
+  discord: {
+    commandDir: './src/commands',
+    eventDir: './src/events',
+    additionalIntents: ['GuildPresences'],
+    additionalPartials: ['Message'],
+  }
+}
+```
+
+Only the keys you specify are overridden — the rest keep their defaults via Stonyx's `mergeObject`.
+
+## Test Config Override
+
+```javascript
+// test/config/environment.js
+export default {
+  discord: {
+    commandDir: './test/sample/discord-commands',
+    eventDir: './test/sample/discord-events',
+    token: 'test-token',
+    serverId: 'test-server',
+    botUserId: 'test-bot',
+  }
+}
+```
+
+Note: Test overrides use the namespaced key (`discord: { ... }`) because they're merged after Stonyx has already namespaced the config.

package/.claude/events.md

@@ -0,0 +1,121 @@
+# Event Handlers
+
+## Overview
+
+Event handlers listen to Discord gateway events. Each handler is a class that extends `EventHandler`, sets a `static event` property, and implements a `handle(...args)` method. Handler files live in the event directory (default: `./discord-events`).
+
+## Base Class
+
+```javascript
+// src/event-handler.js
+export default class EventHandler {
+  static event = null;
+}
+```
+
+The base class provides the `event` default (`null`) and a common prototype.
+
+## Defining an Event Handler
+
+```javascript
+import { EventHandler } from '@stonyx/discord';
+
+export default class MessageCreateHandler extends EventHandler {
+  static event = 'messageCreate';
+
+  handle(message) {
+    if (message.author.bot) return;
+    console.log(`${message.author.username}: ${message.content}`);
+  }
+}
+```
+
+### Required properties
+
+- **`static event`** — the Discord.js gateway event name (e.g., `'messageCreate'`, `'guildMemberAdd'`, `'voiceStateUpdate'`). Must be set on the class, not the instance
+- **`handle(...args)`** — receives the event arguments from Discord.js. The arguments depend on the event type
+
+### Available context
+
+- **`this._bot`** — reference to the `DiscordBot` instance, set automatically during discovery
+
+## Event Handler Discovery
+
+On `DiscordBot.init()`, event handlers are discovered via `forEachFileImport`:
+
+```javascript
+await forEachFileImport(eventDir, (EventHandlerClass, { name }) => {
+  if (!EventHandlerClass.event) {
+    log.discord(`Event handler "${name}" is missing static event property — skipping`);
+    return;
+  }
+
+  const instance = new EventHandlerClass();
+  instance._bot = this;
+  this.eventHandlers.push(instance);
+  log.discord(`Loaded event handler: ${EventHandlerClass.event} (${name})`);
+}, { ignoreAccessFailure: true });
+```
+
+Key details:
+
+- **Storage:** Event handlers are stored in an array (`this.eventHandlers`), not keyed by name. Multiple handlers can listen to the same event
+- **Filename convention:** kebab-case files (`message-create.js`) are converted to camelCase by `forEachFileImport`
+- **Missing directory:** `ignoreAccessFailure: true` means if the event directory doesn't exist, no error is thrown
+- **Validation:** Handlers missing `static event` are logged and skipped
+
+## Event Wiring
+
+After discovery and client creation, each handler is bound to its event:
+
+```javascript
+for (const handler of this.eventHandlers) {
+  client.on(handler.constructor.event, (...args) => handler.handle(...args));
+}
+```
+
+This uses `client.on()` (not `once`), so handlers fire on every occurrence of the event.
+
+## Event-to-Intent Mapping
+
+The framework automatically derives the required intents from registered event handlers. The mapping is defined in `src/intents.js`:
+
+| Event | Required Intents |
+|-------|-----------------|
+| `messageCreate` | `GuildMessages`, `DirectMessages`, `MessageContent` |
+| `messageDelete` | `GuildMessages` |
+| `messageUpdate` | `GuildMessages` |
+| `guildMemberAdd` | `GuildMembers` |
+| `guildMemberRemove` | `GuildMembers` |
+| `inviteCreate` | `GuildInvites` |
+| `inviteDelete` | `GuildInvites` |
+| `voiceStateUpdate` | `GuildVoiceStates` |
+| `interactionCreate` | *(none)* |
+
+Events not in this map do not add any automatic intents. Use `additionalIntents` in config if you need intents for unmapped events.
+
+### Intent-to-Partial Mapping
+
+Some intents require partials to function correctly:
+
+| Intent | Required Partials |
+|--------|------------------|
+| `DirectMessages` | `Channel` |
+
+Additional partials can be added via `additionalPartials` in config.
+
+## Using Bot Utilities in Handlers
+
+```javascript
+import { EventHandler } from '@stonyx/discord';
+
+export default class GuildMemberAddHandler extends EventHandler {
+  static event = 'guildMemberAdd';
+
+  async handle(member) {
+    const welcomeChannelId = '123456789';
+    await this._bot.sendMessage(`Welcome ${member.user.username}!`, welcomeChannelId);
+    await this._bot.giveRole(member.id, 'new-member-role-id');
+  }
+}
+```

package/.claude/index.md

@@ -0,0 +1,36 @@
+# @stonyx/discord — Agent Documentation Index
+
+Comprehensive reference for AI agents working on the `@stonyx/discord` package. Start here, then drill into specific docs as needed.
+
+## Quick Orientation
+
+`@stonyx/discord` is a Stonyx framework module providing a Discord bot with command and event handler auto-discovery, intent auto-derivation, and channel/message/role utilities. It follows the same singleton and module conventions as `@stonyx/sockets` and `@stonyx/events`.
+
+## Documentation
+
+- [architecture.md](./architecture.md) — Module structure, singleton lifecycle, lazy init flow, Stonyx integration, handler discovery lifecycle
+- [commands.md](./commands.md) — Command class API, discovery via forEachFileImport, SlashCommandBuilder usage, skipAuth
+- [events.md](./events.md) — EventHandler class API, discovery, static event property, event-to-intent mapping
+- [configuration.md](./configuration.md) — All config options, env vars, defaults, intent auto-derivation details
+- [testing.md](./testing.md) — Test structure, discord.js mocking patterns, running tests, QUnit patterns
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/main.js` | Entry point — `Discord` default class (Stonyx auto-init) + barrel exports |
+| `src/bot.js` | `DiscordBot` — singleton, command/event discovery, Discord client, utility methods |
+| `src/command.js` | `Command` base class (skipAuth flag) |
+| `src/event-handler.js` | `EventHandler` base class (static event property) |
+| `src/intents.js` | Intent auto-derivation — EVENT_INTENT_MAP, deriveIntents, derivePartials |
+| `src/message.js` | Message chunking utility — chunkMessage, splitAtBoundary |
+| `config/environment.js` | Default config with env var overrides |
+
+## Conventions
+
+- **Singleton pattern:** `if (DiscordBot.instance) return DiscordBot.instance;` in constructor
+- **Stonyx module keywords:** `stonyx-async` + `stonyx-module` in package.json
+- **Config namespace:** `config.discord` (derived from package name `@stonyx/discord` → `discord`)
+- **Logging:** `log.discord()` via `logColor: '#7289da'` + `logMethod: 'discord'` in config
+- **Handler discovery:** `forEachFileImport` from `@stonyx/utils/file`, kebab-to-camelCase naming
+- **Test runner:** `stonyx test` (not plain `qunit`) — bootstraps Stonyx before running tests