Automatic migration to unique usernames

[devin-ai-integration]

To minimise users' cognitive workload, I propose automatic migration to new usernames (spacebarchat#1049) if no username is repeated more than once, and opt-in automatic migration depending on the instance configuration, (may not produce the best-looking names, though) if this is not the case.

---

Originally from spacebarchat/server issue spacebarchat#1051, created by erkinalp, closed as not planned

[traycerai]

Plan

Observations

The codebase is a Discord-like chat server (Spacebar) that currently uses the legacy username + discriminator system. I found evidence of planned "pomelo" (unique username) support with schema fields like unique_username_registration and global_name already present, plus commented references to Config.get().general.uniqueUsernames. The current system generates discriminators (incrementally or randomly) when usernames conflict. Key files include User entity, registration/modification endpoints, and validation utilities. No actual unique username enforcement exists yet - it's all preparatory infrastructure.

Approach

I'll implement automatic migration to unique usernames by:

1. Adding configuration - New uniqueUsernames setting in GeneralConfiguration with modes: "legacy", "auto", "opt_in"
2. Database migration - Add unique constraint on username column and handle existing duplicates
3. Core logic updates - Modify User.register() and username validation to enforce uniqueness when enabled
4. Migration utilities - Create helpers to resolve username conflicts automatically
5. API updates - Update registration and user modification endpoints to support unique usernames
6. Response serialization - Conditionally omit discriminator from API responses when in unique mode

The approach prioritizes backward compatibility while enabling seamless migration when no conflicts exist.

Reasoning

I explored the repository structure and identified this as a Node.js/TypeScript Discord-like server. I examined the User entity to understand the current username+discriminator system, checked registration and authentication flows, found existing "pomelo" references in schemas and gateway code, discovered username validation utilities, and located user modification endpoints. I also found that infrastructure for unique usernames is partially in place but not implemented.

Proposed File Changes

📄 src/util/config/types/GeneralConfiguration.ts ^(MODIFY) 🔗

Add a new uniqueUsernames configuration option to control the username system behavior. This will be an enum-like string with three possible values:

• "legacy" - Use the traditional username + discriminator system (default for backward compatibility)
• "auto" - Automatically migrate to unique usernames if no duplicates exist, otherwise stay in legacy mode
• "opt_in" - Allow users to manually migrate to unique usernames via API endpoints

Add this as a new property in the GeneralConfiguration class with a default value of "legacy" to ensure existing instances continue working without changes.

📄 src/util/migration/postgres/1755800681934-uniqueUsernames.ts ^(NEW) 🔗

References

• 📄 src/util/migration/postgres/1725090962922-applicationProperties.ts

Create a database migration for PostgreSQL that:

1. Add nullable discriminator support - Modify the discriminator column to be nullable to support users who have migrated to unique usernames
2. Add unique constraint conditionally - Create a unique index on the username column, but handle this carefully since existing data may have duplicates
3. Add migration tracking - Add a new column username_migrated (boolean, default false) to track which users have been migrated to unique usernames

The migration should be designed to be reversible and handle cases where duplicate usernames exist. Use conditional logic to only apply the unique constraint if the instance configuration allows it.

📄 src/util/migration/mysql/1755800681934-uniqueUsernames.ts ^(NEW) 🔗

References

• 📄 src/util/migration/mysql/1725090962922-applicationProperties.ts

Create the MySQL version of the unique usernames migration with the same functionality as the PostgreSQL version. This should:

1. Modify discriminator column - Make discriminator nullable
2. Add migration tracking column - Add username_migrated boolean column with default false
3. Handle unique constraint - Add unique index on username column with proper error handling for existing duplicates

Ensure the migration syntax is compatible with MySQL and follows the same pattern as other MySQL migrations in the codebase.

📄 src/util/migration/mariadb/1755800681934-uniqueUsernames.ts ^(NEW) 🔗

References

• 📄 src/util/migration/mariadb/1725090962922-applicationProperties.ts

Create the MariaDB version of the unique usernames migration with the same functionality as the PostgreSQL and MySQL versions. This should:

1. Modify discriminator column - Make discriminator nullable
2. Add migration tracking column - Add username_migrated boolean column with default false
3. Handle unique constraint - Add unique index on username column with proper error handling

Ensure compatibility with MariaDB syntax and follow the existing migration patterns in the mariadb folder.

📄 src/util/entities/User.ts ^(MODIFY) 🔗

References

• 📄 src/util/config/types/GeneralConfiguration.ts ^(MODIFY)

Update the User entity to support unique usernames:

1. Make discriminator nullable - Change the discriminator column to be nullable to support users who have migrated to unique usernames
2. Add migration tracking - Add a new username_migrated boolean column with default false to track migration status
3. Add global_name support - Add an optional global_name column for display names (part of pomelo system)
4. Update generateDiscriminator method - Modify the static generateDiscriminator method to return null when unique usernames are enabled
5. Add unique username utilities - Add new static methods:
   • ensureUniqueUsername(username: string, excludeUserId?: string) - Check if username is available
   • suggestUniqueUsername(baseUsername: string) - Generate available username suggestions
   • migrateToUniqueUsername(userId: string, newUsername?: string) - Migrate a user to unique username system
6. Update validation - Modify the validate() method to handle null discriminators when in unique username mode
7. Update serialization - Modify toPublicUser() and toPrivateUser() methods to conditionally exclude discriminator based on migration status and configuration

📄 src/util/util/UniqueUsernameUtils.ts ^(NEW) 🔗

References

• 📄 src/util/entities/User.ts ^(MODIFY)
• 📄 src/util/util/NameValidation.ts ^(MODIFY)

Create a new utility module for unique username operations:

1. Username conflict resolution - Implement logic to automatically resolve username conflicts by:
   • Checking if a username appears only once (keep as-is)
   • For conflicts, generate variations like username.1234 or username_suffix using snowflake or random suffixes
2. Batch migration utilities - Functions to:
   • Analyze current username conflicts in the database
   • Perform automatic migration when criteria are met (no conflicts or instance config allows)
   • Generate migration reports showing what changes would be made
3. Username suggestion engine - Algorithm to suggest available usernames based on:
   • Original username with numeric suffixes
   • Variations with underscores or dots
   • Shortened versions if original is too long
4. Validation helpers - Functions to validate unique usernames according to the new rules and check availability

This module will be used by the User entity methods and migration scripts.

📄 src/api/routes/auth/register.ts ^(MODIFY) 🔗

References

• 📄 src/util/entities/User.ts ^(MODIFY)
• 📄 src/util/util/UniqueUsernameUtils.ts ^(NEW)
• 📄 src/util/config/types/GeneralConfiguration.ts ^(MODIFY)

Update the registration endpoint to support unique usernames:

1. Check configuration mode - Read Config.get().general.uniqueUsernames to determine behavior
2. Handle unique_username_registration flag - Process the unique_username_registration field from RegisterSchema when present
3. Conditional username validation - When in unique username mode:
   • Skip discriminator generation entirely
   • Use User.ensureUniqueUsername() to validate username availability
   • Throw appropriate errors if username is taken
4. Legacy mode preservation - When in legacy mode, maintain existing discriminator-based registration flow
5. Set migration status - When registering in unique username mode, set username_migrated = true on the new user
6. Handle global_name - Process the optional global_name field from the registration schema

Ensure backward compatibility so existing clients continue to work without changes.

📄 src/api/routes/users/@me/index.ts ^(MODIFY) 🔗

References

• 📄 src/util/entities/User.ts ^(MODIFY)
• 📄 src/util/util/UniqueUsernameUtils.ts ^(NEW)
• 📄 src/util/util/NameValidation.ts ^(MODIFY)

Update the user modification endpoint (PATCH /users/@me) to support unique usernames:

1. Username change logic - When processing username changes:
   • Check if the instance is in unique username mode
   • If in unique mode, validate username uniqueness using User.ensureUniqueUsername()
   • Skip discriminator-related logic when user is migrated to unique usernames
2. Migration support - Allow users to migrate from legacy to unique username system if configuration permits
3. Discriminator handling - When user is in unique username mode, ignore discriminator changes and return appropriate errors
4. Global name support - Add support for updating the global_name field (display name)
5. Validation updates - Use the enhanced username validation that considers the current mode
6. Response updates - Ensure the response properly reflects the user's migration status

Maintain backward compatibility for users still in legacy mode.

📄 src/api/routes/users/@me/pomelo.ts ^(NEW) 🔗

References

• 📄 src/util/entities/User.ts ^(MODIFY)
• 📄 src/util/util/UniqueUsernameUtils.ts ^(NEW)
• 📄 src/api/routes/users/@me/index.ts ^(MODIFY)

Create new pomelo-specific endpoints for unique username management:

1. GET /users/@me/pomelo-suggestions - Return suggested available usernames based on current username
2. POST /users/@me/pomelo-attempt - Check if a specific username is available for migration
3. POST /users/@me/pomelo - Migrate the user to unique username system with specified username

These endpoints should:

• Check if the instance configuration allows unique usernames
• Validate that the user is eligible for migration
• Use the UniqueUsernameUtils for username suggestions and validation
• Update the user's migration status when successful
• Return appropriate error responses for various failure cases

Implement proper rate limiting and validation to prevent abuse.

📄 src/util/schemas/UserModifySchema.ts ^(MODIFY) 🔗

Update the UserModifySchema to support unique username features:

1. Add global_name field - Add optional global_name?: string field for display names
2. Update discriminator handling - Make discriminator field conditional or add validation notes about when it's applicable
3. Add migration fields - Add optional fields for pomelo migration if needed

Ensure the schema remains backward compatible while supporting the new unique username features.

📄 src/util/schemas/PomeloSchema.ts ^(NEW) 🔗

References

• 📄 src/util/schemas/UserModifySchema.ts ^(MODIFY)
• 📄 src/util/schemas/RegisterSchema.ts

Create new schema definitions for pomelo-related API requests:

1. PomeloAttemptSchema - Schema for checking username availability:
   • username: string (required, with validation)
2. PomeloMigrateSchema - Schema for migrating to unique username:
   • username: string (required)
   • global_name?: string (optional display name)
3. PomeloSuggestionsResponse - Response schema for username suggestions:
   • suggestions: string[] (array of available usernames)

Include proper validation annotations and documentation for each schema.

📄 src/gateway/opcodes/Identify.ts ^(MODIFY) 🔗

References

• 📄 src/util/config/types/GeneralConfiguration.ts ^(MODIFY)

Update the Gateway Identify opcode to properly signal pomelo support to clients:

1. Uncomment pomelo disclosure - Replace the commented line // Config.get().general.uniqueUsernames ? ["pomelo"] : [] with actual logic
2. Check configuration - Read the uniqueUsernames configuration and include "pomelo" in the disclose array when unique usernames are enabled (not in "legacy" mode)
3. Client capability signaling - Ensure clients receive proper signals about the server's username system capabilities

This allows compatible clients to adapt their UI and behavior based on the server's username system.

📄 src/util/util/NameValidation.ts ^(MODIFY) 🔗

References

• 📄 src/util/config/types/GeneralConfiguration.ts ^(MODIFY)

Enhance the name validation utility to support unique username requirements:

1. Add unique username validation - Create a new function ValidateUniqueUsername(name: string) that:
   • Applies the same basic validation as ValidateName()
   • Adds additional constraints specific to unique usernames (e.g., no special characters that might cause issues)
   • Checks against reserved usernames that should not be allowed in unique mode
2. Update existing validation - Modify ValidateName() to optionally accept a mode parameter to handle both legacy and unique username validation
3. Export validation modes - Add constants or enums to define validation modes for consistency across the codebase

Ensure the validation is consistent with Discord's pomelo username requirements while allowing instance-specific customization.

📄 scripts/migration/migrateToUniqueUsernames.ts ^(NEW) 🔗

References

• 📄 src/util/util/UniqueUsernameUtils.ts ^(NEW)
• 📄 src/util/entities/User.ts ^(MODIFY)
• 📄 src/util/config/types/GeneralConfiguration.ts ^(MODIFY)

Create a standalone migration script for administrators to migrate their instance to unique usernames:

1. Analysis mode - Scan the database and report:
   • Number of users with duplicate usernames
   • List of conflicts that would need resolution
   • Estimated impact of migration
2. Dry run mode - Show what changes would be made without actually applying them
3. Migration execution - Perform the actual migration:
   • Resolve username conflicts using the conflict resolution logic
   • Update user records to set username_migrated = true
   • Update instance configuration if specified
4. Rollback capability - Provide options to revert the migration if needed
5. Progress reporting - Show progress during migration with detailed logging

Include proper error handling and validation to ensure the migration can be performed safely.

Diagram

sequenceDiagram
    participant Admin as Instance Admin
    participant Config as Configuration
    participant Migration as Migration Script
    participant DB as Database
    participant User as User Registration
    participant API as User API

    Note over Admin, API: Automatic Migration Setup

    Admin->>Config: Set uniqueUsernames = "auto"
    Admin->>Migration: Run analysis script
    Migration->>DB: Check for duplicate usernames
    DB-->>Migration: Return conflict analysis
    Migration-->>Admin: Report: No conflicts found
    Admin->>Migration: Execute automatic migration
    Migration->>DB: Update users set username_migrated = true
    Migration->>DB: Add unique constraint on username
    Migration-->>Admin: Migration complete

    Note over User, API: New User Registration (Unique Mode)

    User->>API: POST /auth/register {username, unique_username_registration: true}
    API->>Config: Check uniqueUsernames setting
    Config-->>API: Mode = "auto" (unique enabled)
    API->>DB: Check username availability
    alt Username available
        DB-->>API: Username unique
        API->>DB: Create user (no discriminator, username_migrated = true)
        API-->>User: Registration successful
    else Username taken
        DB-->>API: Username exists
        API-->>User: Error: Username not available
    end

    Note over User, API: Existing User Migration (Opt-in Mode)

    User->>API: GET /users/@me/pomelo-suggestions
    API->>DB: Generate username suggestions
    API-->>User: Return available usernames
    User->>API: POST /users/@me/pomelo {username: "newname"}
    API->>DB: Validate username availability
    API->>DB: Update user (username, username_migrated = true, discriminator = null)
    API-->>User: Migration successful

Loading

Import In IDE

🤖 Prompt for AI Agents

I have created the following plan after thorough exploration and analysis of the codebase. Follow the below plan verbatim. Trust the files and references. Do not re-verify what's written in the plan. Explore only when absolutely necessary. First implement all the proposed file changes and then I'll review all the changes together at the end.

### Observations

The codebase is a Discord-like chat server (Spacebar) that currently uses the legacy username + discriminator system. I found evidence of planned "pomelo" (unique username) support with schema fields like `unique_username_registration` and `global_name` already present, plus commented references to `Config.get().general.uniqueUsernames`. The current system generates discriminators (incrementally or randomly) when usernames conflict. Key files include User entity, registration/modification endpoints, and validation utilities. No actual unique username enforcement exists yet - it's all preparatory infrastructure.

### Approach

I'll implement automatic migration to unique usernames by:

1. **Adding configuration** - New `uniqueUsernames` setting in GeneralConfiguration with modes: "legacy", "auto", "opt_in"
2. **Database migration** - Add unique constraint on username column and handle existing duplicates
3. **Core logic updates** - Modify User.register() and username validation to enforce uniqueness when enabled
4. **Migration utilities** - Create helpers to resolve username conflicts automatically
5. **API updates** - Update registration and user modification endpoints to support unique usernames
6. **Response serialization** - Conditionally omit discriminator from API responses when in unique mode

The approach prioritizes backward compatibility while enabling seamless migration when no conflicts exist.

### Reasoning

I explored the repository structure and identified this as a Node.js/TypeScript Discord-like server. I examined the User entity to understand the current username+discriminator system, checked registration and authentication flows, found existing "pomelo" references in schemas and gateway code, discovered username validation utilities, and located user modification endpoints. I also found that infrastructure for unique usernames is partially in place but not implemented.

## Mermaid Diagram

sequenceDiagram
    participant Admin as Instance Admin
    participant Config as Configuration
    participant Migration as Migration Script
    participant DB as Database
    participant User as User Registration
    participant API as User API

    Note over Admin, API: Automatic Migration Setup

    Admin->>Config: Set uniqueUsernames = "auto"
    Admin->>Migration: Run analysis script
    Migration->>DB: Check for duplicate usernames
    DB-->>Migration: Return conflict analysis
    Migration-->>Admin: Report: No conflicts found
    Admin->>Migration: Execute automatic migration
    Migration->>DB: Update users set username_migrated = true
    Migration->>DB: Add unique constraint on username
    Migration-->>Admin: Migration complete

    Note over User, API: New User Registration (Unique Mode)

    User->>API: POST /auth/register {username, unique_username_registration: true}
    API->>Config: Check uniqueUsernames setting
    Config-->>API: Mode = "auto" (unique enabled)
    API->>DB: Check username availability
    alt Username available
        DB-->>API: Username unique
        API->>DB: Create user (no discriminator, username_migrated = true)
        API-->>User: Registration successful
    else Username taken
        DB-->>API: Username exists
        API-->>User: Error: Username not available
    end

    Note over User, API: Existing User Migration (Opt-in Mode)

    User->>API: GET /users/@me/pomelo-suggestions
    API->>DB: Generate username suggestions
    API-->>User: Return available usernames
    User->>API: POST /users/@me/pomelo {username: "newname"}
    API->>DB: Validate username availability
    API->>DB: Update user (username, username_migrated = true, discriminator = null)
    API-->>User: Migration successful

## Proposed File Changes

### src/util/config/types/GeneralConfiguration.ts(MODIFY)

Add a new `uniqueUsernames` configuration option to control the username system behavior. This will be an enum-like string with three possible values:

- `"legacy"` - Use the traditional username + discriminator system (default for backward compatibility)
- `"auto"` - Automatically migrate to unique usernames if no duplicates exist, otherwise stay in legacy mode
- `"opt_in"` - Allow users to manually migrate to unique usernames via API endpoints

Add this as a new property in the GeneralConfiguration class with a default value of `"legacy"` to ensure existing instances continue working without changes.

### src/util/migration/postgres/1755800681934-uniqueUsernames.ts(NEW)

References: 

- src/util/migration/postgres/1725090962922-applicationProperties.ts

Create a database migration for PostgreSQL that:

1. **Add nullable discriminator support** - Modify the discriminator column to be nullable to support users who have migrated to unique usernames
2. **Add unique constraint conditionally** - Create a unique index on the username column, but handle this carefully since existing data may have duplicates
3. **Add migration tracking** - Add a new column `username_migrated` (boolean, default false) to track which users have been migrated to unique usernames

The migration should be designed to be reversible and handle cases where duplicate usernames exist. Use conditional logic to only apply the unique constraint if the instance configuration allows it.

### src/util/migration/mysql/1755800681934-uniqueUsernames.ts(NEW)

References: 

- src/util/migration/mysql/1725090962922-applicationProperties.ts

Create the MySQL version of the unique usernames migration with the same functionality as the PostgreSQL version. This should:

1. **Modify discriminator column** - Make discriminator nullable
2. **Add migration tracking column** - Add `username_migrated` boolean column with default false
3. **Handle unique constraint** - Add unique index on username column with proper error handling for existing duplicates

Ensure the migration syntax is compatible with MySQL and follows the same pattern as other MySQL migrations in the codebase.

### src/util/migration/mariadb/1755800681934-uniqueUsernames.ts(NEW)

References: 

- src/util/migration/mariadb/1725090962922-applicationProperties.ts

Create the MariaDB version of the unique usernames migration with the same functionality as the PostgreSQL and MySQL versions. This should:

1. **Modify discriminator column** - Make discriminator nullable
2. **Add migration tracking column** - Add `username_migrated` boolean column with default false  
3. **Handle unique constraint** - Add unique index on username column with proper error handling

Ensure compatibility with MariaDB syntax and follow the existing migration patterns in the mariadb folder.

### src/util/entities/User.ts(MODIFY)

References: 

- src/util/config/types/GeneralConfiguration.ts(MODIFY)

Update the User entity to support unique usernames:

1. **Make discriminator nullable** - Change the discriminator column to be nullable to support users who have migrated to unique usernames
2. **Add migration tracking** - Add a new `username_migrated` boolean column with default false to track migration status
3. **Add global_name support** - Add an optional `global_name` column for display names (part of pomelo system)
4. **Update generateDiscriminator method** - Modify the static `generateDiscriminator` method to return null when unique usernames are enabled
5. **Add unique username utilities** - Add new static methods:
   - `ensureUniqueUsername(username: string, excludeUserId?: string)` - Check if username is available
   - `suggestUniqueUsername(baseUsername: string)` - Generate available username suggestions
   - `migrateToUniqueUsername(userId: string, newUsername?: string)` - Migrate a user to unique username system
6. **Update validation** - Modify the validate() method to handle null discriminators when in unique username mode
7. **Update serialization** - Modify `toPublicUser()` and `toPrivateUser()` methods to conditionally exclude discriminator based on migration status and configuration

### src/util/util/UniqueUsernameUtils.ts(NEW)

References: 

- src/util/entities/User.ts(MODIFY)
- src/util/util/NameValidation.ts(MODIFY)

Create a new utility module for unique username operations:

1. **Username conflict resolution** - Implement logic to automatically resolve username conflicts by:
   - Checking if a username appears only once (keep as-is)
   - For conflicts, generate variations like `username.1234` or `username_suffix` using snowflake or random suffixes
2. **Batch migration utilities** - Functions to:
   - Analyze current username conflicts in the database
   - Perform automatic migration when criteria are met (no conflicts or instance config allows)
   - Generate migration reports showing what changes would be made
3. **Username suggestion engine** - Algorithm to suggest available usernames based on:
   - Original username with numeric suffixes
   - Variations with underscores or dots
   - Shortened versions if original is too long
4. **Validation helpers** - Functions to validate unique usernames according to the new rules and check availability

This module will be used by the User entity methods and migration scripts.

### src/api/routes/auth/register.ts(MODIFY)

References: 

- src/util/entities/User.ts(MODIFY)
- src/util/util/UniqueUsernameUtils.ts(NEW)
- src/util/config/types/GeneralConfiguration.ts(MODIFY)

Update the registration endpoint to support unique usernames:

1. **Check configuration mode** - Read `Config.get().general.uniqueUsernames` to determine behavior
2. **Handle unique_username_registration flag** - Process the `unique_username_registration` field from `RegisterSchema` when present
3. **Conditional username validation** - When in unique username mode:
   - Skip discriminator generation entirely
   - Use `User.ensureUniqueUsername()` to validate username availability
   - Throw appropriate errors if username is taken
4. **Legacy mode preservation** - When in legacy mode, maintain existing discriminator-based registration flow
5. **Set migration status** - When registering in unique username mode, set `username_migrated = true` on the new user
6. **Handle global_name** - Process the optional `global_name` field from the registration schema

Ensure backward compatibility so existing clients continue to work without changes.

### src/api/routes/users/@me/index.ts(MODIFY)

References: 

- src/util/entities/User.ts(MODIFY)
- src/util/util/UniqueUsernameUtils.ts(NEW)
- src/util/util/NameValidation.ts(MODIFY)

Update the user modification endpoint (PATCH /users/@me) to support unique usernames:

1. **Username change logic** - When processing username changes:
   - Check if the instance is in unique username mode
   - If in unique mode, validate username uniqueness using `User.ensureUniqueUsername()`
   - Skip discriminator-related logic when user is migrated to unique usernames
2. **Migration support** - Allow users to migrate from legacy to unique username system if configuration permits
3. **Discriminator handling** - When user is in unique username mode, ignore discriminator changes and return appropriate errors
4. **Global name support** - Add support for updating the `global_name` field (display name)
5. **Validation updates** - Use the enhanced username validation that considers the current mode
6. **Response updates** - Ensure the response properly reflects the user's migration status

Maintain backward compatibility for users still in legacy mode.

### src/api/routes/users/@me/pomelo.ts(NEW)

References: 

- src/util/entities/User.ts(MODIFY)
- src/util/util/UniqueUsernameUtils.ts(NEW)
- src/api/routes/users/@me/index.ts(MODIFY)

Create new pomelo-specific endpoints for unique username management:

1. **GET /users/@me/pomelo-suggestions** - Return suggested available usernames based on current username
2. **POST /users/@me/pomelo-attempt** - Check if a specific username is available for migration
3. **POST /users/@me/pomelo** - Migrate the user to unique username system with specified username

These endpoints should:
- Check if the instance configuration allows unique usernames
- Validate that the user is eligible for migration
- Use the `UniqueUsernameUtils` for username suggestions and validation
- Update the user's migration status when successful
- Return appropriate error responses for various failure cases

Implement proper rate limiting and validation to prevent abuse.

### src/util/schemas/UserModifySchema.ts(MODIFY)

Update the UserModifySchema to support unique username features:

1. **Add global_name field** - Add optional `global_name?: string` field for display names
2. **Update discriminator handling** - Make discriminator field conditional or add validation notes about when it's applicable
3. **Add migration fields** - Add optional fields for pomelo migration if needed

Ensure the schema remains backward compatible while supporting the new unique username features.

### src/util/schemas/PomeloSchema.ts(NEW)

References: 

- src/util/schemas/UserModifySchema.ts(MODIFY)
- src/util/schemas/RegisterSchema.ts

Create new schema definitions for pomelo-related API requests:

1. **PomeloAttemptSchema** - Schema for checking username availability:
   - `username: string` (required, with validation)
2. **PomeloMigrateSchema** - Schema for migrating to unique username:
   - `username: string` (required)
   - `global_name?: string` (optional display name)
3. **PomeloSuggestionsResponse** - Response schema for username suggestions:
   - `suggestions: string[]` (array of available usernames)

Include proper validation annotations and documentation for each schema.

### src/gateway/opcodes/Identify.ts(MODIFY)

References: 

- src/util/config/types/GeneralConfiguration.ts(MODIFY)

Update the Gateway Identify opcode to properly signal pomelo support to clients:

1. **Uncomment pomelo disclosure** - Replace the commented line `// Config.get().general.uniqueUsernames ? ["pomelo"] : []` with actual logic
2. **Check configuration** - Read the `uniqueUsernames` configuration and include "pomelo" in the disclose array when unique usernames are enabled (not in "legacy" mode)
3. **Client capability signaling** - Ensure clients receive proper signals about the server's username system capabilities

This allows compatible clients to adapt their UI and behavior based on the server's username system.

### src/util/util/NameValidation.ts(MODIFY)

References: 

- src/util/config/types/GeneralConfiguration.ts(MODIFY)

Enhance the name validation utility to support unique username requirements:

1. **Add unique username validation** - Create a new function `ValidateUniqueUsername(name: string)` that:
   - Applies the same basic validation as `ValidateName()`
   - Adds additional constraints specific to unique usernames (e.g., no special characters that might cause issues)
   - Checks against reserved usernames that should not be allowed in unique mode
2. **Update existing validation** - Modify `ValidateName()` to optionally accept a mode parameter to handle both legacy and unique username validation
3. **Export validation modes** - Add constants or enums to define validation modes for consistency across the codebase

Ensure the validation is consistent with Discord's pomelo username requirements while allowing instance-specific customization.

### scripts/migration/migrateToUniqueUsernames.ts(NEW)

References: 

- src/util/util/UniqueUsernameUtils.ts(NEW)
- src/util/entities/User.ts(MODIFY)
- src/util/config/types/GeneralConfiguration.ts(MODIFY)

Create a standalone migration script for administrators to migrate their instance to unique usernames:

1. **Analysis mode** - Scan the database and report:
   - Number of users with duplicate usernames
   - List of conflicts that would need resolution
   - Estimated impact of migration
2. **Dry run mode** - Show what changes would be made without actually applying them
3. **Migration execution** - Perform the actual migration:
   - Resolve username conflicts using the conflict resolution logic
   - Update user records to set `username_migrated = true`
   - Update instance configuration if specified
4. **Rollback capability** - Provide options to revert the migration if needed
5. **Progress reporting** - Show progress during migration with detailed logging

Include proper error handling and validation to ensure the migration can be performed safely.

---

Developer Humor

Why did the discriminator break up with the username?
Because it found out there was a #1 chance of staying unique! 🎭
Now username's living its best single life,
No more sharing, no more strife! ✨

┌─────────────┐  
│ username123 │ ← Free at last!  
└─────────────┘  
(no #1234 needed)

---

Execution Information

Branch: master
Commit: e031e72

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.