roleping-bot/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

A Telegram bot built with GramIO that enables role-based mentions in group chats. Users can create custom roles, join/leave them, and mention all role members at once using @mentions or commands.

## Development Commands

- `pnpm dev` - Run bot in development mode with hot reload
- `pnpm start` - Run bot in production mode
- `pnpm drizzle-kit generate --config=src/shared/database/config.ts` - Generate database migrations after schema changes
- `pnpm drizzle-kit migrate --config=src/shared/database/config.ts` - Apply pending migrations to database
- `pnpm drizzle-kit studio --config=src/shared/database/config.ts` - Open Drizzle Studio for database inspection

## Architecture

### Core Components

**Bot Entry Point** (`src/index.ts` → `src/bot/index.ts`)
- Bot initialization uses GramIO framework
- Commands are auto-loaded from `src/bot/commands/` using `@gramio/autoload`
- Two middleware handlers in `src/bot/index.ts`:
  1. Message handler for @mention syntax (e.g., `@rolename`) - triggers role mentions
  2. Command handler for bare commands (e.g., `/rolename`) - also triggers role mentions
- Bot username is captured on startup to properly handle commands with @botname suffix

**Database** (PostgreSQL with Drizzle ORM)
- Schema defined in `src/shared/database/schema.ts`
- Three tables: `roles` (id, slug, aliases, chatId), `role_members` (id, roleId, userId), and `chat_configs` (id, chatId, roleManagePermission, roleMentionPermission)
- Configuration in `src/shared/database/config.ts`
- Path aliases use `@/*` mapping to `./src/*`

**Services** (`src/shared/services/`)
- `RoleService` - All role and role member database operations
- `MentionService` - Handles mentioning all members of a role
  - Chunks members into groups of 5 to avoid hitting Telegram's limits
  - Builds mention entities using GramIO's `mention()` helper
  - Sends multiple messages if role has >5 members, with pagination indicators
- `ChatConfigService` - Manages per-chat permission configuration
  - Lazy initialization via `getOrCreate()` - configs created on first access
  - Defaults: `all_admins` for role management, `everyone` for mentions
- `PermissionService` - Centralized permission checking logic
  - `canManageRoles()` - Checks if user can add/delete roles based on chat config
  - `canMentionRoles()` - Checks if user can trigger role mentions based on chat config

**Commands** (`src/bot/commands/`)
- Admin commands require chat admin permissions (checked via `isChatAdmin()`)
- `/roleadd <name>` - Create new role (permission configurable, updates bot commands dynamically)
- `/roledel` - Delete role (permission configurable)
- `/join <name>` - Join a role (always available to everyone)
- `/leave <name>` - Leave a role (always available to everyone)
- `/myroles` - List your roles
- `/roles` - List all roles in chat
- `/config` - View and configure permissions (any admin can view, owner can change via inline buttons)
- `/reload` - Refresh admin cache (any admin)

**Role Triggering**
- Roles can be triggered two ways:
  1. Via @mention in any message (e.g., "hey @developers")
  2. Via bare command (e.g., "/developers" or "/developers@botname")
- Both methods call `MentionService.mentionAll()`

**Utilities**
- `src/bot/utilities/perms.ts` - Permission checking utilities
  - `isChatAdmin()` - Checks if user is admin (uses 1-hour cache)
  - `isChatOwner()` - Checks if user is chat creator/owner
  - `getAdminInfo()` - Returns detailed admin info with granular permissions
  - `hasAdminPermission()` - Checks specific Telegram admin permissions (can_promote_members, can_change_info, can_manage_chat)
  - `refreshAdminCache()` - Clears admin cache for a specific chat
  - Admin cache: 1-hour TTL to reduce Telegram API calls, falls back to stale data on error
  - Handles hidden admins including anonymous admin bot ID 1087968824
- `src/bot/utilities/constants.ts` - Role name validation regex and reserved command names
- `src/shared/utilities/chunk.ts` - Array chunking utility for member batching

### Important Patterns

**Permission System**
- Chat owners can configure permissions via `/config` command with inline keyboard navigation
- Role management options: `everyone`, `all_admins`, `admin_can_promote_members`, `admin_can_change_info`, `admin_can_manage_chat`, `only_owner`
- Role mention options: `everyone`, `all_admins`, `only_owner`
- Permissions checked via `PermissionService` which consults `chat_configs` table
- Join/leave functionality always available to everyone (no configuration)
- Admin cache with 1-hour TTL reduces Telegram API calls - use `/reload` to manually refresh

**Role Name Validation**
- Must match `ROLE_NAME_REGEX`: 4-32 characters, letters only
- Cannot use `RESERVED_NAMES` (built-in command names)

**Chat Scope**
- All roles are scoped to `chatId` - same role name can exist in different chats
- Bot only works in groups/supergroups, not private chats

**Dynamic Command Registration**
- When admin creates/deletes roles, bot updates chat-specific command list via `setMyCommands()` with scope type 'chat'
- This allows autocomplete for role names in that specific chat

**Environment Variables**
- Required: `DATABASE_URL`, `BOT_TOKEN`
- Optional: `NODE_ENV` (defaults to 'production')
- Loaded via Node's `loadEnvFile()` from `.env` file

### Database Migrations

After modifying `src/shared/database/schema.ts`, generate and apply migrations using drizzle-kit with the explicit config path:
- `pnpm drizzle-kit generate --config=src/shared/database/config.ts`
- `pnpm drizzle-kit migrate --config=src/shared/database/config.ts`

The migration output directory is `./drizzle/`.

**Current Schema:**
- `roles` - Role definitions with slug, aliases, and chatId
- `role_members` - User memberships in roles
- `chat_configs` - Per-chat permission configuration (lazy-initialized)
  - Enums: `role_manage_permission` and `role_mention_permission`
  - Default values ensure backwards compatibility with existing chats