Initialer Bot Upload

AGENTS-BOT.md

@@ -0,0 +1,75 @@
+# AI Agent Guide: Modular Discord Bot Architecture
+
+This document is intended for AI agents to understand, recreate, or extend the `pixelpoebel` Discord bot. It describes the design patterns, conventions, and key considerations for this specific modular architecture.
+
+## 🏗 Architecture Overview
+
+The bot uses a **Modular Command & Event Loading** pattern with **ESM (ECMAScript Modules)** and **TypeScript**.
+
+### Key Design Patterns:
+1.  **Extended Client Pattern:** We extend the `discord.js` `Client` class to hold global state like the `commands` Collection. This avoids global variables and improves type safety.
+2.  **Dynamic Discovery:** The `src/index.ts` entry point uses `readdirSync` and dynamic `import()` to automatically register any command or event found in the `src/commands` or `src/events` directories.
+3.  **Interface-Driven Commands:** All commands must implement the `Command` interface defined in `src/structures/Command.ts`.
+4.  **Persistent SQLite Database:** The bot uses `better-sqlite3` for data persistence. It's initialized in `src/structures/Database.ts` and stores data in the `data/` directory.
+5.  **Twitch Monitoring Service:** The `TwitchManager` in `src/structures/` handles periodic API polling and notification logic.
+6.  **Granular Permission Handling:** Commands like `twitch.ts` use manual permission checks (`interaction.memberPermissions.has(PermissionFlagsBits.Administrator)`) to allow a mix of public and restricted subcommands within a single command.
+
+## 💾 Database Interaction
+
+To use the database in any command or event:
+```typescript
+import { DB } from '../../structures/Database.js';
+
+// Example: Get one row
+const user = DB.get('SELECT * FROM mod_logs WHERE user_id = ?', userId);
+
+// Example: Insert data
+DB.run('INSERT INTO mod_logs (guild_id, user_id, action) VALUES (?, ?, ?)', guildId, userId, 'WARN');
+```
+
+**Persistence:** In Docker, the `data/` folder is mapped to a volume to ensure data survives container restarts.
+
+## 📡 Twitch API Implementation
+
+The bot uses the **Twitch Helix API** with a client credentials flow. It requires:
+- `TWITCH_CLIENT_ID`
+- `TWITCH_CLIENT_SECRET`
+
+**Workflow:**
+- `TwitchManager.getAccessToken()`: Handles token acquisition and automatic renewal.
+- `TwitchManager.fetchStreamData(channelName)`: Helper for real-time status checks.
+- `TwitchManager.checkStreams()`: Periodically checks the status of monitored streamers from the database.
+- `TwitchManager.sendNotification()`: Constructs and sends an embed with live stream details to the designated Discord channel.
+
+## 🚀 How to Extend
+
+### Adding a Command:
+1.  Navigate to `src/commands/`.
+2.  Create a subfolder for the category (e.g., `utility`, `owner`, `moderation`).
+3.  Create a file (e.g., `ping.ts`).
+4.  Implement the `Command` interface and `export default`.
+5.  Run `npm run deploy` (or use `/deploy` in Discord) to register it with Discord.
+
+### Adding an Event:
+1.  Navigate to `src/events/`.
+2.  Create a file (e.g., `messageCreate.ts`).
+3.  `export default` an object with `name`, `once` (optional), and `execute`.
+
+## ⚠️ Critical AI Agent Constraints
+
+1.  **Environment Variables:** Always use `process.env.DISCORD_TOKEN`, `CLIENT_ID`, `TWITCH_CLIENT_ID`, and `TWITCH_CLIENT_SECRET`. **Never hardcode credentials.**
+2.  **Type-Safe Casting:** When using `interaction.options.getMember('target')`, always cast to `GuildMember` if you need guild-specific methods like `.kick()`.
+3.  **Interaction States:** Remember to check `interaction.replied` or `interaction.deferred` before replying in error handlers to avoid "Interaction already replied" errors.
+4.  **Deployment:** Slash commands are NOT automatically registered on bot start. You MUST run the `deploy-commands.ts` script whenever the command data changes.
+5.  **Owner-Checks:** Use `client.application.owner` to verify permissions for owner-only commands.
+
+## 📦 Replication Checklist for Agents
+- [ ] Initialize NPM project with ESM.
+- [ ] Set up `tsconfig.json` for NodeNext.
+- [ ] Create `ExtendedClient.ts` to store commands.
+- [ ] Create `index.ts` with dynamic folder loading logic.
+- [ ] Create `deploy-commands.ts` for REST registration.
+- [ ] Implement global error handling in `interactionCreate.ts`.
+- [ ] Initialize SQLite database in `index.ts` via `DB.init()`.
+- [ ] Set up `TwitchManager` for stream monitoring.
+- [ ] Enable `Message Content Intent` in Discord Developer Portal if message tracking is needed.