cleanup

Decomposed the monolithic `dispatch()` method into modular components using `CommandPrecondition`, `ResultHandler`, and `UsageValidator`. Replaced inline checks and tightly-coupled logic with composable, testable classes, eliminating `instanceof` dependencies. Preserved existing behavior and improved maintainability for future feature additions.

.dockerignore

@@ -0,0 +1,15 @@
+.git
+.github
+.idea
+.mvn
+src
+classes
+logs
+target/*
+!target/netneutrality.jar
+*.iml
+README.md
+checkstyle.xml
+mvnw
+mvnw.cmd
+pom.xml

.env.example

@@ -1,17 +1,24 @@
+NETNEUTRALITY_TAG=latest
+
 NETNEUTRALITY_BOT_ENV=dev
 NETNEUTRALITY_BOT_TOKEN=
 NETNEUTRALITY_BOT_PREFIX=$
 NETNEUTRALITY_BOT_OWNER=
+NETNEUTRALITY_BOT_INVITE=
 NETNEUTRALITY_API_PORT=9000
 
 MYSQL_HOST=127.0.0.1
-MYSQL_USER=root
-MYSQL_PASSWORD=
-MYSQL_DATABASE=
 MYSQL_PORT=3306
+MYSQL_USER=java
+MYSQL_PASSWORD=password
+MYSQL_DATABASE=netneutrality
+MYSQL_ROOT_PASSWORD=password
+MARIADB_AUTO_UPGRADE=1
 
 NETNEUTRALITY_PO_TOKEN=
 NETNEUTRALITY_VISITOR_DATA=
+NETNEUTRALITY_CIPHER_URL=http://localhost:8001
+NETNEUTRALITY_CIPHER_PASSWORD=
 
 NETNEUTRALITY_SENTRY_DSN=
 GITLAB_HOST=

.github/workflows/ci.yml

@@ -0,0 +1,133 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - "main"
+    tags:
+      - '*'
+  pull_request:
+    branches:
+      - "main"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  package:
+    name: Package
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Set up JDK
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5
+        with:
+          distribution: 'temurin'
+          java-version: '25'
+          cache: 'maven'
+
+      - name: Build package
+        run: |
+          chmod +x ./mvnw
+          ./mvnw --batch-mode --update-snapshots verify
+
+      - name: Upload test reports
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: junit-reports
+          path: |
+            **/target/*-reports/TEST-*.xml
+          if-no-files-found: ignore
+
+      - name: Upload Maven artifacts
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: maven-artifacts
+          path: |
+            target/netneutrality.jar
+            startup.sh
+          if-no-files-found: error
+
+  maven-publish:
+    name: Publish Maven Package
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    needs: package
+    if: ${{ github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Set up JDK
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5
+        with:
+          distribution: 'temurin'
+          java-version: '25'
+          cache: 'maven'
+          server-id: gitea
+          server-username: REGISTRY_USER
+          server-password: REGISTRY_PASSWORD
+
+      - name: Publish Maven package
+        run: |
+          chmod +x ./mvnw
+          ./mvnw --batch-mode deploy -DskipTests
+        env:
+          REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
+          REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
+
+  docker:
+    name: Docker Build and Push
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    needs: package
+    if: ${{ github.event_name == 'push' }}
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: maven-artifacts
+          path: .
+
+      - name: Compute Docker tags
+        id: meta
+        shell: bash
+        run: |
+          REGISTRY="${{ secrets.REGISTRY_URL }}/${{ secrets.REGISTRY_USER }}/netneutrality"
+          if [[ "$GITHUB_REF" == refs/tags/* ]]; then
+            ver="${GITHUB_REF_NAME#v}"
+            echo "tags=${REGISTRY}:${ver},${REGISTRY}:latest" >> "$GITHUB_OUTPUT"
+          else
+            echo "tags=${REGISTRY}:main" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to registry
+        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4
+        with:
+          registry: ${{ secrets.REGISTRY_URL }}
+          username: ${{ secrets.REGISTRY_USER }}
+          password: ${{ secrets.REGISTRY_PASSWORD }}
+
+      - name: Build and push
+        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.gitignore

@@ -45,3 +45,4 @@ target/
 logs/
 
 .env
+docker-compose.override.yml

.gitlab-ci.yml

@@ -1,54 +0,0 @@
-image: eclipse-temurin:17-jdk-alpine
-
-variables:
-  MAVEN_OPTS: >-
-    -Dhttps.protocols=TLSv1.2
-    -Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository
-    -Dorg.slf4j.simpleLogger.showDateTime=true
-    -Djava.awt.headless=true
-
-  MAVEN_CLI_OPTS: >-
-    --batch-mode
-    --errors
-    --fail-at-end
-    --show-version
-    --no-transfer-progress
-    -DinstallAtEnd=true
-    -DdeployAtEnd=true
-
-cache:
-  key: "maven-$CI_COMMIT_REF_SLUG"
-  paths:
-    - .m2/repository
-
-stages:
-  - compile
-  - test
-  - package
-
-compile:
-  stage: compile
-  script:
-    - "chmod +x ./mvnw"
-    - "./mvnw $MAVEN_CLI_OPTS compile"
-
-test:
-  stage: test
-  script:
-    - "chmod +x ./mvnw"
-    - "./mvnw $MAVEN_CLI_OPTS test"
-  artifacts:
-    when: always
-    reports:
-      junit:
-        - "**/target/*-reports/TEST-*.xml"
-
-package:
-  stage: package
-  script:
-    - "chmod +x ./mvnw"
-    - "./mvnw $MAVEN_CLI_OPTS package -DskipTests=true"
-  artifacts:
-    name: "Maven artifacts from $CI_PROJECT_NAME on $CI_COMMIT_REF_SLUG"
-    paths:
-      - "**/target"

.junie/plans/decouple-command-processor.md

@@ -0,0 +1,178 @@
+---
+sessionId: session-260910-075746-nw8q
+---
+
+# Requirements
+
+### Overview & Goals
+Refactor `CommandProcessor` to break its tightly coupled `dispatch()` method into composable, extensible pieces so that new preconditions, permission strategies, and result handlers can be added without modifying the processor itself.
+
+### Scope
+**In Scope**
+- Decompose `CommandProcessor.dispatch()` into a pipeline of single-responsibility components
+- Eliminate `instanceof` checks for `InteractionContext` / `SlashCommandContext` inside the processor
+- Preserve all existing behavior and keep the existing test suite green
+
+**Out of Scope**
+- Changes to the `Command` interface or individual command implementations
+- Changes to `CommandContext` subclass hierarchy
+- Changes to `CommandContainer`, `CommandRegistry`, or `CommandExecutionResult`
+
+# Technical Design
+
+### Current Implementation
+`CommandProcessor.dispatch()` (~80 lines, `CommandProcessor.java:48-129`) performs **five concerns** sequentially:
+1. **Command lookup** — resolve command from registry
+2. **Precondition checks** — guild-only, slash-only, via `instanceof` checks against `InteractionContext`
+3. **Permission check** — `canExecute()` with `instanceof SlashCommandContext`
+4. **Usage/argument validation** — `checkUsage()` + `checkOptions()`, again branching on `instanceof InteractionContext`
+5. **Execution & result handling** — execute command, handle TASK/ERROR/WARN/NOACTION results, catch exceptions
+
+The `instanceof` checks (lines 66, 197, 220) tightly couple the processor to specific context subtypes, making it impossible to add new context types without modifying the processor.
+
+### Key Decisions
+1. **Introduce a `CommandPrecondition` interface** — each check (guild-only, slash-only, permissions) becomes a standalone, testable precondition that can be composed into an ordered list. This replaces the inline if-chains and eliminates instanceof checks from the processor.
+2. **Move context-type-specific logic into the context itself** — instead of `instanceof` checks in the processor, add polymorphic methods to `CommandContext` (e.g., `supportsSlashOnly()`, `canSkipPermissionCheck()`, `validateOptions()`). Each context subclass overrides as needed.
+3. **Extract result handling into a `ResultHandler`** — the if-chain for TASK/ERROR/WARN/NOACTION becomes a dedicated component, making it easy to add new result types.
+4. **Keep changes incremental** — refactor in place without changing the public API of `CommandProcessor` (constructor + `dispatch()` remain the same). The pipeline is internal.
+
+### Proposed Changes
+
+#### 1. `CommandPrecondition` interface
+```java
+// New file: core/command/precondition/CommandPrecondition.java
+public interface CommandPrecondition {
+    /** Returns null if passed, or an error message to reply with. */
+    String check(CommandContext context, Command command);
+}
+```
+Concrete implementations:
+- `GuildOnlyPrecondition` — replaces lines 60-64
+- `SlashCommandOnlyPrecondition` — replaces lines 66-69, uses `context.supportsSlashOnly()` instead of instanceof
+- `PermissionPrecondition` — replaces `canExecute()` (lines 215-229), uses `context.canSkipPermissionCheck()` instead of instanceof
+
+#### 2. Polymorphic methods on `CommandContext`
+Add to `CommandContext`:
+- `boolean isInteraction()` — default `false`, overridden to `true` in `InteractionContext`
+- `boolean canSkipPermissionCheck()` — default `false`, overridden in `SlashCommandContext`
+
+This eliminates all `instanceof` checks from the processor.
+
+#### 3. `CommandResultHandler`
+```java
+// New file: core/command/CommandResultHandler.java
+public class CommandResultHandler {
+    void handle(CommandContext context, CommandExecutionResult result, TaskManager taskManager);
+}
+```
+Encapsulates the TASK/ERROR/WARN/NOACTION/message reply logic from lines 100-120.
+
+#### 4. Refactored `CommandProcessor.dispatch()`
+The method becomes:
+```java
+public void dispatch() {
+    CommandContainer container = resolveCommand();
+    if (container == null) return;
+    
+    Command command = container.getCommand();
+    context.setCommand(command);
+    configureSentry(command);
+    
+    for (CommandPrecondition precondition : preconditions) {
+        String error = precondition.check(context, command);
+        if (error != null) { context.replyEphemeral(error); return; }
+    }
+    
+    if (!usageValidator.validate(context, container)) return;
+    
+    try {
+        CommandExecutionResult result = command.execute(context);
+        resultHandler.handle(context, result, taskManager);
+    } catch (...) { /* existing error handling */ }
+}
+```
+
+### Architecture Diagram
+```mermaid
+graph LR
+    D[dispatch] --> R[resolveCommand]
+    R --> P[Preconditions Loop]
+    P --> GuildOnly
+    P --> SlashOnly
+    P --> Permission
+    P --> UV[UsageValidator]
+    UV --> E[command.execute]
+    E --> RH[ResultHandler]
+```
+
+### File Structure
+| File | Action |
+|------|--------|
+| `core/command/precondition/CommandPrecondition.java` | **New** — interface |
+| `core/command/precondition/GuildOnlyPrecondition.java` | **New** |
+| `core/command/precondition/SlashCommandOnlyPrecondition.java` | **New** |
+| `core/command/precondition/PermissionPrecondition.java` | **New** |
+| `core/command/CommandResultHandler.java` | **New** |
+| `core/command/UsageValidator.java` | **New** — extracted from `checkUsage()`/`checkOptions()` |
+| `core/command/CommandProcessor.java` | **Modified** — delegate to above components |
+| `core/context/CommandContext.java` | **Modified** — add `isInteraction()`, `canSkipPermissionCheck()` |
+| `core/context/InteractionContext.java` | **Modified** — override `isInteraction()` |
+| `context/command/SlashCommandContext.java` | **Modified** — override `canSkipPermissionCheck()` |
+| `CommandProcessorTest.java` | **Modified** — update construction, add unit tests for new components |
+
+### Risks
+- **Behavioral regression** — the refactor must preserve exact reply messages and ordering. Mitigated by the existing 1000+ line test suite.
+- **Precondition ordering matters** — guild-only must run before permission check. The list order is explicit and documented.
+
+# Testing
+
+### Validation Approach
+- All existing `CommandProcessorTest` tests must pass unchanged (behavior preservation).
+- New unit tests for each precondition, the result handler, and the usage validator in isolation.
+
+### Key Scenarios
+- Preconditions short-circuit in order (guild-only before permissions)
+- Custom precondition can be added to the list and is invoked
+- ResultHandler correctly dispatches TASK to TaskManager, logs ERROR/WARN
+- UsageValidator handles all subcommand/group/option combinations
+
+### Edge Cases
+- Null command from container
+- Empty precondition list (all checks pass)
+- InteractionContext skips option validation in UsageValidator
+
+# Delivery Steps
+
+### ✓ Step 1: Add polymorphic methods to CommandContext hierarchy
+CommandContext subclasses expose their capabilities without requiring instanceof checks.
+
+- Add `isInteraction()` (default `false`) and `canSkipPermissionCheck()` (default `false`) to `CommandContext.java`
+- Override `isInteraction()` to return `true` in `InteractionContext.java`
+- Override `canSkipPermissionCheck()` to return `true` in `SlashCommandContext.java`
+- Verify existing tests still compile and pass
+
+### ✓ Step 2: Extract preconditions into CommandPrecondition interface and implementations
+Precondition checks become standalone, composable components.
+
+- Create `CommandPrecondition` interface in `core/command/precondition/`
+- Implement `GuildOnlyPrecondition` — checks `command.isGuildOnly()` and `context.isFromGuild()`
+- Implement `SlashCommandOnlyPrecondition` — checks `command.isSlashCommandOnly()` and `context.isInteraction()`
+- Implement `PermissionPrecondition` — replaces `canExecute()`, uses `context.canSkipPermissionCheck()` instead of instanceof
+- Add unit tests for each precondition
+
+### ✓ Step 3: Extract UsageValidator and CommandResultHandler
+Usage validation and result handling become dedicated classes.
+
+- Extract `checkUsage()` and `checkOptions()` into `UsageValidator.java`, replacing `instanceof InteractionContext` with `context.isInteraction()`
+- Extract result-handling if-chain (TASK/ERROR/WARN/NOACTION + reply) into `CommandResultHandler.java`
+- Add unit tests for both classes
+
+### ✓ Step 4: Refactor CommandProcessor to use the new components
+CommandProcessor.dispatch() becomes a thin orchestrator delegating to the extracted components.
+
+- Replace inline precondition checks with a `List<CommandPrecondition>` loop
+- Replace `checkUsage()`/`checkOptions()` calls with `UsageValidator`
+- Replace result-handling if-chain with `CommandResultHandler`
+- Remove the now-unused private methods (`canExecute`, `checkUsage`, `checkOptions`)
+- Keep constructor backward-compatible or provide a builder/factory for custom precondition lists
+- Run full `CommandProcessorTest` suite to confirm behavioral equivalence

.junie/plans/di-lifecycle-refactor.md

@@ -0,0 +1,302 @@
+---
+sessionId: session-260826-092009-17wb
+---
+
+# Requirements
+
+### Overview & Goals
+
+Replace the singleton/static-heavy bootstrap of the bot with an explicit, deterministic **lifecycle-managed application** driven by a small hand-rolled `ApplicationContext` and a `Lifecycle` contract. Dependencies are wired through **constructors** (including for reflectively-loaded commands and tasks), and **interfaces** are introduced for the key services so the code becomes testable, maintainable, and mockable — without adopting Spring Boot or any DI framework.
+
+The current design (documented in `docs/architecture.md`) uses:
+- `NetNeutrality` as a static singleton holding `instance` and `jda`, with a manual, order-sensitive `startup()`/`shutdown()` chain.
+- Static singletons everywhere: `Settings.getInstance()`, `SessionManager` (static `getSessionFactory`/`shutdown`), `CommandManager` (static `init`/maps), `TaskManager.getInstance()`, `MusicManager` (static factory + static `playerManager`), `ThreadManager` (static executors), `ScheduledTaskManager` (static), `GuildService.get(...)` (static cache).
+- `ReflectionHelper` instantiating commands/tasks via **no-arg constructors**, which forces them to reach out to singletons.
+
+### Scope
+
+**In Scope**
+- A `Lifecycle` interface (`start()`/`stop()`/`priority()`) and an `ApplicationContext` that owns instances, wires them, and drives ordered startup/shutdown.
+- Converting the core singletons to constructor-injected **instances**.
+- Introducing **interfaces for key services** (settings, persistence/session, executors, command registry, task manager, music service, guild-service provider) — decision confirmed with the user.
+- Reworking `ReflectionHelper` + command/task base classes to use **constructor injection** (decision confirmed).
+- Symmetric, deterministic startup/shutdown replacing `NetNeutrality.startup()/shutdown()` and the JVM shutdown hook.
+- **Reorganizing the package layout** into `bootstrap` / `framework` / `platform` / `feature` / `data` / `shared` (see the Package Structure tab), done in the same effort as the DI refactor so imports are touched once. This includes renaming the entry point `NetNeutrality` → `App`.
+
+**Out of Scope**
+- Introducing Spring Boot, Guice, or Dagger (explicitly rejected — manual context chosen).
+- Full interface-per-service/repository abstraction (only key services get interfaces).
+- Dropping the `O*`/`G*` entity name prefixes (optional cosmetic churn, deferred).
+- Behavioral/feature changes to commands, tasks, music, or the web API — this is a structural refactor only.
+- Database schema / Flyway migration changes.
+
+### User Stories
+- As a maintainer, I want services created and wired in one explicit place so the dependency graph and startup order are obvious and not implicit.
+- As a maintainer, I want symmetric `start()`/`stop()` for every component so shutdown reliably tears down what startup created, in reverse order.
+- As a developer, I want commands/tasks to receive their dependencies via constructor so they no longer call `getInstance()` and can be unit-tested with mocks.
+- As a developer, I want key services behind interfaces so I can mock them in tests (building on the existing JUnit 5 + Mockito setup).
+
+### Functional Requirements
+- The bot must start and shut down with identical externally-observable behavior to today (same ordered steps from `docs/architecture.md`).
+- Startup order must be preserved: persistence/session → migrations → executors → command/task registries → music sources → JDA → web API → presence.
+- Shutdown must run in reverse of startup: cancel scheduled tasks → disconnect music players → shut down executors → shut down JDA → release the Hibernate registry.
+- Commands and tasks discovered by `ReflectionHelper` must continue to auto-load ("drop a class in the package" model) but now receive dependencies via constructor.
+- No public command/task behavior changes.
+
+### Non-Functional Requirements
+- **No new runtime dependencies** (manual container only).
+- **Incremental & low-risk**: migrate one area at a time using temporary static shims that delegate to the context, so the build stays green throughout.
+- **Compatibility**: fat-JAR packaging and `main` entry point (`me.bobert.netneutrality.NetNeutrality`) remain unchanged.
+- **Testability**: instance + interface-based services must be mockable with Mockito.
+
+# Technical Design
+
+### Current Implementation
+
+- **Bootstrap** — `NetNeutrality` (`src/main/java/me/bobert/netneutrality/NetNeutrality.java`): static `instance`, static `jda`, `main()` builds `Settings` implicitly, constructor calls `startup()` which chains `SessionManager.getSessionFactory()` → `DatabaseMigration.migrate()` → `CommandManager.init()` → `MusicManager.initPlayerManager()` → `TaskManager.getInstance().init()` → `initJDA()` → `CommandManager.registerSlashCommands(jda)` → `new EventsHandler()` → `new WebApi(port)` → presence → shutdown hook. `shutdown()` runs `ScheduledTaskManager.cancelAll()` → `MusicManager.disconnectPlayers()` → `ThreadManager.shutdownExecutor()` → `disconnect()` → `SessionManager.shutdown()`.
+- **Singletons/statics**: `Settings` (`utils/Settings.java`), `SessionManager` (`core/db/SessionManager.java`, all-static), `CommandManager` (`core/command/CommandManager.java`, static `commands` map + static `init`), `TaskManager` (`core/tasks/TaskManager.java`, `getInstance()`), `MusicManager` (`music/MusicManager.java`, static `managers` map + static `playerManager` + static `get`/`initPlayerManager`/`disconnectPlayers`), `ThreadManager` (`core/thread/ThreadManager.java`, static executors), `ScheduledTaskManager`, `GuildService` (`db/service/GuildService.java`, static `services` cache).
+- **Reflective instantiation** — `ReflectionHelper.loadClassesFromPackage(...)` calls `s.getConstructor().newInstance()` (no-arg), used by `CommandManager.initCommands()` and `TaskManager.loadBuiltInTasks()/loadScheduledTasks()`.
+- **Consumers of singletons** — ~110 call sites across commands (`command/**`), tasks (`tasks/**`), contexts (`context/**`, `core/context/**`), HTTP handlers (`http/server/**`), `EventsHandler`, repositories/services (`db/**`), etc.
+
+### Key Decisions (confirmed with user)
+1. **Manual `ApplicationContext` + `Lifecycle`** — no DI framework; the context owns instances, wires them via constructors, and drives ordered `start()`/`stop()`.
+2. **Constructor injection for commands/tasks** — `ReflectionHelper` resolves a constructor that accepts the context (or specific dependencies) and passes them in; commands/tasks store deps as final fields instead of calling `getInstance()`.
+3. **Lifecycle + key service interfaces** — introduce a `Lifecycle` interface plus interfaces for the main services (settings, persistence/session, executors, command registry, task manager, music service, guild-service provider). Repositories and minor helpers stay concrete.
+4. **Package restructure to `bootstrap`/`framework`/`platform`/`feature`/`data`/`shared`** — separate code by reason-of-change (engine vs. cross-cutting infra vs. concrete features vs. persistence model vs. leaf helpers), consolidate each feature vertical (e.g. music) into one package, and dissolve the catch-all `utils`. Performed right after the DI wiring, via the IDE's safe "Move Class" refactor, so the ~110 import updates happen once. Full details in the Package Structure tab.
+
+### Proposed Changes
+
+**1. Lifecycle contract** — new `me.bobert.netneutrality.bootstrap.Lifecycle`:
+```java
+public interface Lifecycle {
+    void start() throws Exception;
+    default void stop() {}
+    default int priority() { return 0; } // lower = started earlier, stopped later
+}
+```
+
+**2. Application context** — new `me.bobert.netneutrality.bootstrap.ApplicationContext`:
+```java
+public final class ApplicationContext {
+    private final List<Lifecycle> components = new ArrayList<>();
+    public <T> T register(T component) {
+        if (component instanceof Lifecycle l) components.add(l);
+        return component;
+    }
+    public void start() throws Exception {
+        components.sort(Comparator.comparingInt(Lifecycle::priority));
+        for (Lifecycle c : components) c.start();
+    }
+    public void stop() {
+        var reversed = new ArrayList<>(components);
+        Collections.reverse(reversed);
+        reversed.forEach(Lifecycle::stop);
+    }
+}
+```
+The context also exposes typed getters for wired services so `ReflectionHelper`/`EventsHandler`/contexts can resolve dependencies.
+
+**3. Convert singletons to instances behind interfaces** (priority values in parentheses set start order):
+- `SettingsProvider` ← `Settings` (config; constructed first, not itself a `Lifecycle`).
+- `SessionProvider`/persistence ← `SessionManager` instance implementing `Lifecycle` (10): `start()` builds the `SessionFactory` + runs `DatabaseMigration.migrate()`; `stop()` destroys the registry.
+- `ExecutorProvider` ← `ThreadManager` instance implementing `Lifecycle` (20): `stop()` = current `shutdownExecutor()`.
+- `CommandRegistry` ← `CommandManager` instance implementing `Lifecycle` (30): `start()` = `init()`; `registerSlashCommands(jda)` called after JDA is ready.
+- `TaskManager` interface ← impl implementing `Lifecycle` (30): `start()` = current `init()`.
+- Scheduled tasks ← `ScheduledTaskManager` instance implementing `Lifecycle`: `stop()` = `cancelAll()`.
+- `MusicService` ← new factory owning the shared `AudioPlayerManager` + per-guild `MusicManager` map, implementing `Lifecycle` (40): `start()` = `initPlayerManager()`; `stop()` = `disconnectPlayers()`. Per-guild `MusicManager` becomes a plain instance created by the factory.
+- `GuildServiceProvider` ← registry owning the guild cache (replaces static `GuildService.get`).
+- `WebApi` becomes a `Lifecycle` (60): `start()` binds the HTTP server; `stop()` stops it.
+- JDA is built by the context (replacing static `jda`) and exposed via a getter/provider.
+
+**4. Rework reflective instantiation** — extend `ReflectionHelper` so `loadClassesFromPackage` accepts a factory/`ApplicationContext` and instantiates via a constructor that takes the needed dependencies (falling back to no-arg for classes that declare it). `CommandManager.initCommands()` and `TaskManager.loadBuiltInTasks()/loadScheduledTasks()` pass the context so commands/tasks are constructor-injected.
+
+**5. Migrate consumers off `getInstance()`** — command/task base classes (`core/tasks/impl/AbstractTask.java`, `AbstractStepTask`, `AbstractPersistableTask`, `core/command/impl/MusicCommand.java`) and contexts (`core/context/AbstractContext.java`, `context/**`) take dependencies via constructor. `EventsHandler` is constructed with the context and passes services when building contexts. During migration, keep **temporary static shims** (e.g. `Settings.getInstance()` delegating to the context instance) so untouched call sites keep compiling; remove them at the end.
+
+**6. New bootstrap** — `NetNeutrality.main()` builds the `ApplicationContext`, constructs and `register()`s services in dependency order, calls `context.start()`, and installs **one** shutdown hook calling `context.stop()`. Static `instance`/`jda` are removed.
+
+### Data Models / Contracts
+Key new interfaces (illustrative signatures):
+```java
+interface SettingsProvider { String get(String key); String get(String key, String def); String getPrefix(); }
+interface SessionProvider extends Lifecycle { org.hibernate.SessionFactory getSessionFactory(); }
+interface ExecutorProvider extends Lifecycle { java.util.concurrent.ExecutorService getExecutor(String name); java.util.concurrent.ScheduledExecutorService getScheduledExecutor(); }
+interface CommandRegistry extends Lifecycle { CommandContainer getCommandContainer(String name); void registerSlashCommands(JDA jda); }
+interface TaskManager extends Lifecycle { Task getTask(String id); void insert(CommandContext ctx, Task task); void handle(TaskContext ctx); /* ... */ }
+interface MusicService extends Lifecycle { MusicManager get(net.dv8tion.jda.api.entities.Guild guild); }
+interface GuildServiceProvider { GuildService get(String guildId); }
+```
+
+### File Structure
+New DI classes are created directly in their **target** packages (from the Package Structure tab) so they are not moved twice.
+- **Added**: `bootstrap/Lifecycle.java`, `bootstrap/ApplicationContext.java`; service interfaces `platform/config/SettingsProvider.java`, `platform/persistence/SessionProvider.java`, `platform/concurrency/ExecutorProvider.java`, `framework/command/CommandRegistry.java`, `framework/task/TaskManager.java` [interface] + impl, `feature/music/MusicService.java`, `data/service/GuildServiceProvider.java`.
+- **Moved / renamed (package restructure)**: `core` → `framework` (engine only); `core.db` + `db` → `platform.persistence` + `data`; `core.thread` → `platform.concurrency`; `hooks` → `platform.event`; `http` → `platform.web`; `utils` dissolved into `platform.config` / `platform.persistence` / `bootstrap` / `shared.util`; `NetNeutrality` → `App`. See the Package Structure tab.
+- **Modified**: `App.java` (bootstrap), `ReflectionHelper.java` (constructor injection), all converted managers/services, command/task base classes, `EventsHandler.java`, `WebApi.java`, HTTP handlers, `getInstance()` call sites, and `pom.xml` / `Dockerfile` / `startup.sh` for the `mainClass` rename.
+- **Docs**: update `docs/architecture.md` (startup/shutdown + package map) and `docs/utilities-and-bootstrap.md` (bootstrap) to reflect the context and new layout.
+
+### Architecture Diagram
+```mermaid
+graph TD
+    Main["NetNeutrality.main()"] --> Ctx[ApplicationContext]
+    Ctx -->|constructs & wires| Settings[SettingsProvider]
+    Ctx -->|register + start/stop| Session[SessionProvider]
+    Ctx -->|register + start/stop| Exec[ExecutorProvider]
+    Ctx -->|register + start/stop| Cmd[CommandRegistry]
+    Ctx -->|register + start/stop| Tasks[TaskManager]
+    Ctx -->|register + start/stop| Music[MusicService]
+    Ctx -->|register + start/stop| Web[WebApi]
+    Ctx -->|builds| JDA[JDA]
+    Cmd -->|constructor-injects| Refl[ReflectionHelper]
+    Tasks -->|constructor-injects| Refl
+    Refl -->|ctor deps| Impl[Commands / Tasks]
+    JDA -->|events| Events[EventsHandler]
+    Events -->|builds contexts with deps| Cmd
+    Events --> Tasks
+```
+
+### Risks
+- **Large call-site surface (~110 usages)** — mitigated by temporary static shims delegating to context instances, migrating area-by-area, keeping the build green.
+- **Startup ordering regressions** — mitigated by encoding order via `Lifecycle.priority()` and mirroring the exact sequence from `docs/architecture.md`.
+- **Reflective constructor resolution** — commands/tasks must expose a consistent injectable constructor; mitigate by supporting a no-arg fallback and validating all classes load at startup.
+- **Per-guild `MusicManager` vs shared factory** — clarify that the shared `AudioPlayerManager` and cache move to the `MusicService`, while per-guild `MusicManager` stays a lightweight instance.
+- **`SessionManager.System.exit(1)` on DB failure** — preserve fail-fast behavior inside the new `SessionProvider.start()`.
+
+# Package Structure
+
+### Current Layout Problems
+The tree today mixes three organizing principles at once: abstraction-vs-impl (`core.command`↔`command`, `core.context`↔`context`, `core.tasks`↔`tasks`), infra-vs-data (`core.db`↔`db`), and no split at all (`music`, `http`, `utils`, `hooks`). Consequences:
+- `core` is simultaneously "the engine" and "misc" — it holds the framework sub-packages **and** loose classes (`LogHandler`, `BotState`).
+- A single feature is scattered: music lives in `core.command.impl.MusicCommand`, `command.music`, `context.MusicChannelContext`, `tasks.music`, and `music/` — five places.
+- `utils` is a catch-all mixing config (`Settings`), reflection (`ReflectionHelper`), JPA glue (`JpaUtils`), and formatting (`MessageFunction`, `UserFunction`).
+- Naming drift: `db.entities` (plural) vs. the singular convention elsewhere.
+
+### Guiding Principle
+Separate code by the reason it changes:
+- **framework** — the reusable bot engine (command/task/context machinery); rarely changes, knows nothing about specific commands.
+- **platform** — cross-cutting technical services (persistence, concurrency, config, logging, event dispatch, web); changes when tech/tooling changes.
+- **feature** — concrete commands + tasks + contexts + domain logic, grouped **by feature vertical**; changes most often.
+- **data** — the persistence model (entities, repositories, services).
+- **shared** — genuinely cross-feature leaf helpers.
+
+### Target Layout
+```
+me.bobert.netneutrality
+├── App.java                 // was NetNeutrality (main + bootstrap entry)
+├── bootstrap/               // ApplicationContext, Lifecycle, ReflectionHelper (composition root)
+├── framework/               // the reusable engine (was core, minus the misc)
+│   ├── command/             // Command, CommandProcessor, CommandRegistry, options, build, impl bases
+│   ├── context/             // Context hierarchy, reply/
+│   └── task/                // Task, TaskManager, StepTask/PersistableTask, persistence/, trait/, impl bases
+├── platform/                // cross-cutting technical services (horizontals)
+│   ├── config/              // Settings / SettingsProvider
+│   ├── persistence/         // SessionProvider, DatabaseMigration, Repository base, JpaUtils
+│   ├── concurrency/         // ExecutorProvider, ScheduledTaskManager, BaseThreadFactory
+│   ├── logging/             // LogHandler
+│   ├── event/               // EventsHandler (was hooks)
+│   └── web/                 // WebApi, handlers, WebModule (was http)
+├── feature/                 // concrete features, one vertical per package
+│   ├── music/               // MusicService/MusicManager, QueueManager, scheduler, source/, + music commands/tasks/contexts
+│   ├── moderation/          // blacklist, purge, admin commands + related services
+│   ├── reaction/            // reaction commands + emoji-role tasks
+│   ├── git/                 // report-issue command + task
+│   ├── crypto/
+│   └── help/
+├── data/                    // the persistence model (was the "db" half of the split)
+│   ├── entity/              // O* entities (entities → entity, singular)
+│   ├── repository/
+│   └── service/             // GuildService, GuildServiceProvider, BlacklistService, …
+├── shared/util/             // MiscUtils, MessageFunction, UserFunction, GuildUtils, ContextUtils
+└── exceptions/              // unchanged (already coherent)
+```
+
+### Key Moves
+- `core` → `framework`, now containing **only** the engine (no `LogHandler`, no `BotState`, no `db`, no `thread`).
+- `core.db` (infra) → `platform.persistence`; `db` (model) → `data` — resolves the "`db` means two things" problem. `db.entities` → `data.entity`.
+- `core.thread` → `platform.concurrency`; `hooks` → `platform.event`; `http` → `platform.web`.
+- `utils` dissolved: config → `platform.config`, JPA glue → `platform.persistence`, reflection → `bootstrap`, formatting/misc → `shared.util`.
+- All music code consolidates under `feature.music`; the other verticals group their command/task/context/service triplets similarly.
+- `LogHandler` → `platform.logging`; `BotState` → `bootstrap` (composition-root-adjacent state).
+
+### Sequencing & Rationale
+The repackage is done **immediately after the DI wiring, in the same effort**: the DI refactor already renames managers (`CommandManager`→`CommandRegistry`, `SessionManager`→`SessionProvider`, `ThreadManager`→`ExecutorProvider`) and touches imports at ~110 call sites, so combining them avoids editing the same imports twice. Moves use the IDE's safe **"Move Class"** refactor (references update automatically), one subsystem at a time, building after each. New DI classes are created directly in their target packages rather than moved later.
+
+### Lower-Risk Variant (optional fallback)
+If full feature-first grouping feels too large in one pass, a high-value subset fixes ~80% of the confusion with far fewer moves: rename `core` → `framework`, extract `platform` (evict `LogHandler`, `BotState`, `core.db`, `core.thread`, `hooks`, `http`), and dissolve `utils` — while leaving the concrete `command`/`task`/`context` packages where they are. The trade-off is that a single feature stays spread across those layer packages.
+
+### Risks
+- **Move touches nearly every import** — mitigated by IDE "Move Class" (auto-updates references), one subsystem per step, and a build after each move.
+- **Main-class rename `NetNeutrality` → `App`** — must update the Shade `mainClass` in `pom.xml`, the `Dockerfile`/`startup.sh` entry, and docs atomically, or the fat JAR won't launch.
+- **Feature-first churn** — grouping music/moderation/etc. is the largest move; the lower-risk variant above is the fallback if needed.
+
+# Testing
+
+### Validation Approach
+The refactor is behavior-preserving, so validation focuses on: (a) the project compiles and the fat JAR builds after each stage, (b) existing tests still pass, and (c) new unit tests prove services are now mockable/instance-based. Use the existing Maven + JUnit 5 + Mockito setup (`./mvnw test`); Checkstyle runs in the `test` phase and must stay green.
+
+### Key Scenarios
+- **Build & Checkstyle** — `./mvnw package` succeeds after every stage (shade fat JAR, main class unchanged).
+- **ApplicationContext ordering** — a unit test registers fake `Lifecycle` components with different `priority()` values and asserts `start()` runs ascending and `stop()` runs descending.
+- **Command/task loading** — assert `CommandManager`/`TaskManager` still discover and instantiate all implementations via `ReflectionHelper` with constructor injection (no `getInstance()` calls at runtime).
+- **Existing tests** — `CommandProcessorTest`, `SettingsTest`, and any others continue to pass; update them to use injected instances/mocks instead of wrestling with singletons.
+
+### Edge Cases
+- Missing `NETNEUTRALITY_BOT_TOKEN` → startup still fails fast with a clear error.
+- DB connection failure inside `SessionProvider.start()` → preserves current fail-fast (Sentry capture in non-dev + exit).
+- A command/task class that only declares a no-arg constructor → `ReflectionHelper` still loads it via the fallback path.
+- Shutdown with services that never fully started → `stop()` must be null-safe (mirroring current guards like `jda != null`, `registry != null`).
+
+### Test Changes
+- **Add**: `ApplicationContextTest` (ordering + symmetric start/stop), a `ReflectionHelper` constructor-injection test.
+- **Update**: `SettingsTest` and `CommandProcessorTest` to construct instances/mocks of the new interfaces instead of relying on static singletons.
+- **Skip**: no integration test against a live Discord gateway or real MySQL (out of scope).
+
+# Delivery Steps
+
+### ✓ Step 1: Introduce Lifecycle contract and ApplicationContext bootstrap
+The app boots through an `ApplicationContext` that drives ordered start/stop, while behavior stays identical via temporary shims.
+
+- Add `me.bobert.netneutrality.bootstrap.Lifecycle` interface with `start()`, `stop()` (default no-op), and `priority()` (default 0, lower = started earlier / stopped later).
+- Add `me.bobert.netneutrality.bootstrap.ApplicationContext` that registers components, sorts by `priority()`, starts ascending and stops descending, and exposes typed getters for wired services.
+- Refactor `NetNeutrality.main()`/`startup()` to build the context and register the existing (still static) steps as thin `Lifecycle` adapters, install a single shutdown hook calling `context.stop()`, and remove static `instance`/`jda` (temporarily bridged where needed).
+- Add `ApplicationContextTest` asserting ascending start and descending stop ordering.
+
+### ✓ Step 2: Convert foundational services to instances behind interfaces
+Configuration, persistence, and executors are constructor-injected instances behind interfaces, wired into the context with correct lifecycle order.
+
+- Introduce `SettingsProvider` implemented by `Settings` (instance, constructed first); keep `Settings.getInstance()` as a temporary shim delegating to the context instance.
+- Convert `core/db/SessionManager` into a `SessionProvider` instance implementing `Lifecycle` (priority ~10): `start()` builds the `SessionFactory` and runs `DatabaseMigration.migrate()`, `stop()` destroys the registry; preserve fail-fast on DB errors.
+- Convert `core/thread/ThreadManager` into an `ExecutorProvider` instance implementing `Lifecycle` (priority ~20) with `stop()` = current `shutdownExecutor()`.
+- Update `JpaUtils`/`Repository`/`db/**` call sites andhihims to use the injected providers.
+
+### ✓ Step 3: Convert domain managers (command, task, scheduled, music, guild) to instances behind interfaces
+The command/task/music/guild managers are instance-based `Lifecycle` components behind interfaces, registered in the context.
+
+- Introduce `CommandRegistry` (impl = `CommandManager`, priority ~30): `start()` = `init()`; `registerSlashCommands(jda)` invoked after JDA is ready.
+- Introduce a `TaskManager` interface + impl (priority ~30) implementing `Lifecycle` with `start()` = current `init()`; convert `ScheduledTaskManager` to an instance whose `stop()` = `cancelAll()`.
+- Introduce `MusicService` factory owning the shared `AudioPlayerManager` and per-guild `MusicManager` map (priority ~40): `start()` = `initPlayerManager()`, `stop()` = `disconnectPlayers()`; make per-guild `MusicManager` a plain instance created by the factory.
+- Introduce `GuildServiceProvider` owning the guild cache, replacing static `GuildService.get(...)`.
+- Keep static shims on each so untouched call sites keep compiling.
+
+### ✓ Step 4: Enable constructor injection for reflectively-loaded commands and tasks
+Commands and tasks receive their dependencies via constructor instead of calling `getInstance()`.
+
+- Extend `ReflectionHelper.loadClassesFromPackage` to accept the `ApplicationContext` and instantiate via a constructor taking the required dependencies, with a no-arg fallback for classes that declare it.
+- Update `CommandManager.initCommands()` and `TaskManager.loadBuiltInTasks()/loadScheduledTasks()` to pass the context.
+- Update command/task base classes (`core/tasks/impl/AbstractTask`, `AbstractStepTask`, `AbstractPersistableTask`, `core/command/impl/MusicCommand`) and contexts (`core/context/AbstractContext`, `context/**`, `EventsHandler`) to store injected dependencies as final fields.
+- Add a `ReflectionHelper` test proving constructor injection and no-arg fallback both work.
+
+### ✓ Step 5: Remove static shims, finalize interfaces, and update tests/docs
+All singletons/`getInstance()` accessors are gone; services are wired only through the context, and tests/docs reflect the new model.
+
+- Migrate remaining `getInstance()`/static call sites (commands, tasks, HTTP handlers in `http/server/**`, `LogHandler`, `BotState`) to injected interfaces and delete the temporary static shims and singleton fields.
+- Convert `WebApi` into a `Lifecycle` component (priority ~60) with `start()`/`stop()` for the HTTP server.
+- Update `SettingsTest` and `CommandProcessorTest` to use injected instances/mocks of the new interfaces; ensure `./mvnw package` (including Checkstyle) is green.
+- Update `docs/architecture.md` (startup/shutdown lifecycle) and `docs/utilities-and-bootstrap.md` (bootstrap) to describe the `ApplicationContext` + `Lifecycle` design.
+
+### ✓ Step 6: Reorganize packages into bootstrap/framework/platform/feature/data/shared
+The codebase is regrouped by reason-of-change into the target layout (see the Package Structure tab), with all references updated and the build green.
+
+- Rename the entry point `NetNeutrality` → `App`, and update the Shade `mainClass` in `pom.xml`, plus the `Dockerfile`/`startup.sh` launch entry.
+- Using the IDE's safe "Move Class" refactor, one subsystem per step: `core` → `framework` (engine only); `core.db` + `db` → `platform.persistence` + `data` (`db.entities` → `data.entity`); `core.thread` → `platform.concurrency`; `hooks` → `platform.event`; `http` → `platform.web`.
+- Dissolve `utils`: `Settings`/`SettingsProvider` → `platform.config`, `JpaUtils` → `platform.persistence`, `ReflectionHelper` → `bootstrap`, formatting/misc helpers → `shared.util`; move `LogHandler` → `platform.logging` and `BotState` → `bootstrap`.
+- Consolidate each feature vertical (music, moderation, reaction, git, crypto, help) into `feature.*`, pulling its commands/tasks/contexts/services together.
+- Build and run tests after each subsystem move; update `docs/architecture.md` "Package map" to the new layout.

.junie/plans/improve-music-manager.md

@@ -0,0 +1,95 @@
+---
+sessionId: session-260905-173932-36te
+---
+
+# Requirements
+
+### Overview & Goals
+Improve the `MusicManager` class for better maintainability, testability, and separation of concerns.
+
+### Scope
+**In Scope:**
+- Refactor `MusicManager` to reduce responsibilities
+- Extract vote-skip logic into a dedicated service
+- Fix synchronization strategy
+- Improve error handling
+- Eliminate magic numbers
+
+**Out of Scope:**
+- Changing `QueueManager` or `TrackScheduler` internals (beyond reducing circular refs)
+- Changing external behavior or command interfaces
+
+# Technical Design
+
+### Current Issues
+
+1. **Vote-skip business logic in MusicManager** (lines 113–145): The `voteSkip()` method contains complex voting logic (threshold calculation, member counting, skip decisions) that doesn't belong in a player manager. Magic number `2.1` is used as a vote divisor with no explanation.
+
+2. **Circular dependencies**: `MusicManager` → `TrackScheduler` → `QueueManager` → `TrackScheduler` → `MusicManager`. This makes testing and reasoning about the code difficult.
+
+3. **Overly broad `synchronized` methods**: Nearly every public method is `synchronized` on `this`, even simple getters like `getCurrentlyPlaying()` and `isCurrentlyPlaying()`. This creates unnecessary contention. Methods like `getQueueSize()` aren't synchronized at all, creating inconsistency.
+
+4. **Poor error handling in `connect()`** (line 80): Throws a bare `RuntimeException` when `audioChannel` is null instead of using `IllegalArgumentException` or returning a `CommandExecutionResult`.
+
+5. **`baseVolume` parsed from String without error handling** (line 44): `Integer.parseInt()` can throw `NumberFormatException` with no fallback.
+
+### Proposed Changes
+
+#### 1. Extract `VoteSkipService`
+- New class: `me.bobert.netneutrality.music.VoteSkipService`
+- Moves all vote-skip logic out of `MusicManager`
+- Replace magic `2.1` with a named constant `VOTE_THRESHOLD_DIVISOR` or configurable guild setting
+- `MusicManager.voteSkip()` delegates to the new service
+
+#### 2. Reduce circular dependencies
+- `TrackScheduler` and `QueueManager` should not need to call back into `MusicManager` for `disconnect()`. Instead, use a callback/listener interface (e.g., `MusicManagerCallback`) that `TrackScheduler` holds, breaking the direct circular reference.
+
+#### 3. Fix synchronization
+- Remove `synchronized` from simple delegating methods (`getCurrentlyPlaying()`, `isCurrentlyPlaying()`, `resume()`, `stopTrack()`) — `AudioPlayer` is already thread-safe.
+- Keep `synchronized` only on methods that coordinate multiple state changes (`connect()`, `disconnect()`, `play()`).
+- Make `getQueueSize()` consistent with the chosen strategy.
+
+#### 4. Improve error handling
+- `connect()`: Replace `RuntimeException` with `IllegalArgumentException("audioChannel must not be null")`
+- `baseVolume`: Add try-catch with a sensible default (e.g., 50) and a warning log.
+
+#### 5. Extract constants
+- `VOTE_THRESHOLD_DIVISOR = 2.1` (or make configurable)
+- `MIN_MEMBERS_FOR_VOTE = 3`
+- `DEFAULT_VOLUME = 50`
+
+### File Structure
+| File | Action |
+|------|--------|
+| `music/MusicManager.java` | Modify — remove vote logic, fix sync, fix error handling |
+| `music/VoteSkipService.java` | **New** — extracted vote-skip logic |
+| `music/MusicManagerCallback.java` | **New** — interface to break circular dependency |
+| `music/TrackScheduler.java` | Modify — use callback interface instead of direct `MusicManager` reference where possible |
+| `music/QueueManager.java` | Modify — remove `getMusicManager()` call chain for disconnect |
+
+# Delivery Steps
+
+### ✓ Step 1: Extract VoteSkipService and constants
+Vote-skip logic is isolated in a new service class and magic numbers are replaced with named constants.
+
+- Create `VoteSkipService.java` in `me.bobert.netneutrality.music`
+- Move the vote-skip logic from `MusicManager.voteSkip()` into `VoteSkipService.voteSkip(CommandContext, QueueManager, AudioChannel)`
+- Define constants: `VOTE_THRESHOLD_DIVISOR`, `MIN_MEMBERS_FOR_VOTE`
+- Update `MusicManager.voteSkip()` to delegate to the new service
+- Add `DEFAULT_VOLUME` constant and wrap `baseVolume` parsing in try-catch with fallback
+
+### ✓ Step 2: Fix synchronization and error handling
+Synchronization is applied only where needed and error handling is improved.
+
+- Remove `synchronized` from simple delegating methods: `getCurrentlyPlaying()`, `isCurrentlyPlaying()`, `resume()`, `stopTrack()`, `setVolume()`
+- Keep `synchronized` on `connect()`, `disconnect()`, `play()`, `isNotConnectedTo()`
+- Replace `RuntimeException` in `connect()` with `IllegalArgumentException`
+- Ensure `getQueueSize()` follows the same synchronization strategy as other methods
+
+### ✓ Step 3: Reduce circular dependencies between MusicManager, TrackScheduler, and QueueManager
+The circular reference chain is broken using a callback interface.
+
+- Create `MusicManagerCallback.java` interface with method `void onQueueEmpty()` (or similar) to replace direct `MusicManager.disconnect()` calls from `QueueManager`
+- Have `MusicManager` implement the callback interface
+- Update `TrackScheduler` constructor to accept the callback interface instead of the full `MusicManager` where only disconnect/connection behavior is needed
+- Update `QueueManager.clearQueue()` to use the callback instead of `scheduler.getMusicManager().disconnect()`

.junie/plans/queue-scheduler-improvements.md

@@ -0,0 +1,132 @@
+---
+sessionId: session-260906-073726-sbxb
+---
+
+# Requirements
+
+### Overview & Goals
+Improve the code quality, correctness, and maintainability of `QueueManager`, `TrackScheduler`, `TrackInfo`, and `VoteSkipService` — the core music queue and playback scheduling subsystem.
+
+### Scope
+**In Scope:**
+- Fix thread-safety issues (check-then-act race conditions in `QueueManager`)
+- Simplify confusing queue insertion logic in `QueueManager.queue()`
+- Separate concerns: extract command-result formatting from queue data operations
+- Fix `TrackInfo` using wrong logger (`QueueManager.class` instead of `TrackInfo.class`)
+- Clean up `TrackScheduler.onTrackStuck()` complexity
+- Add unit tests for `QueueManager`, `TrackScheduler`, `TrackInfo`, and `VoteSkipService`
+- Expose skip-vote state through `TrackInfo` more cleanly (encapsulate the `Set<String>` skips)
+
+**Out of Scope:**
+- Changes to `MusicManager`, `MusicServiceImpl`, or audio source/loading classes
+- New user-facing features or commands
+- Changes to `MusicManagerCallback` interface
+
+# Technical Design
+
+### Current Implementation
+
+**`QueueManager`** (`src/main/java/me/bobert/netneutrality/music/QueueManager.java`, 286 lines):
+- Manages a `LinkedBlockingDeque<TrackInfo>` with manual `synchronized` blocks
+- Multiple methods check state outside the synchronized block, then re-check inside (e.g., `clearQueue()` L81 vs L86, `skip()` L197 vs L203, `shuffle()` L229 vs L233, `removeFromQueue()` L254 vs L259) — the outer checks are racy and misleading
+- `queue()` method (L135-158) has confusing branching: `addFirst` + `add` can result in the same track being added twice when `player.getPlayingTrack() == null && !queue.isEmpty()`
+- `clearQueue()` calls `callback.onQueueEmpty()` before checking if queue is empty (L79)
+- `removeTracksFromUser()` iterates the queue outside synchronized (L97), then again inside (L102)
+- `skip(int)` silently resets `nbTrack` to 1 if it exceeds queue size (L209) — surprising behavior
+- Mixes queue data operations with `CommandExecutionResult` formatting
+
+**`TrackScheduler`** (`src/main/java/me/bobert/netneutrality/music/TrackScheduler.java`, 175 lines):
+- `onTrackStuck()` (L129-173) has deeply nested logic with inline async recovery — hard to follow and test
+- Circular dependency: creates `QueueManager` in constructor, which takes `this` back
+- `context` field is accessed from multiple threads but only `attachContext`/`detachContext` are synchronized — `getContext()`, `getDj()` are not
+
+**`TrackInfo`** (`src/main/java/me/bobert/netneutrality/music/TrackInfo.java`, 83 lines):
+- Logger incorrectly uses `QueueManager.class` (L26) instead of `TrackInfo.class`
+- `getSkips()` returns mutable `Set<String>` — breaks encapsulation
+- Duplicate copyright block (L1-5 and L7-11)
+
+**`VoteSkipService`** (`src/main/java/me/bobert/netneutrality/music/VoteSkipService.java`, 57 lines):
+- Relatively clean, but directly calls `queueManager.skip()` mixing vote logic with queue mutation
+- `info.addSkip()` uses `context.getGuildUser()` but `info.getSkips().size()` check uses raw set — no race protection
+
+### Proposed Changes
+
+#### QueueManager
+1. **Remove all outer unsynchronized checks** — move all logic inside a single `synchronized` block per method to eliminate check-then-act races
+2. **Rewrite `queue()` method** — simplify to: add to queue, if nothing playing start the head track. Remove the confusing `addFirst`/`add` dual-path
+3. **Fix `clearQueue()`** — move `callback.onQueueEmpty()` call to after the queue is confirmed non-empty and cleared
+4. **Fix `skip(int)`** — when `nbTrack > queue.size()`, skip all remaining tracks instead of silently resetting to 1
+5. **Fix `removeTracksFromUser()`** — do all filtering inside synchronized block
+6. **Return queue operation results as data** (e.g., number removed, track name) and let callers build `CommandExecutionResult` — or at minimum, document that this class returns command results
+
+#### TrackScheduler
+1. **Extract stuck-track recovery** into a dedicated `StuckTrackRecoveryHandler` class to reduce `onTrackStuck()` complexity
+2. **Make `context` access thread-safe** — synchronize `getContext()` and `getDj()`, or use `volatile`
+3. **Add `lastStuckTrack` reset** on track start or successful recovery to prevent stale state
+
+#### TrackInfo
+1. **Fix logger** — change to `TrackInfo.class`
+2. **Remove duplicate copyright block**
+3. **Encapsulate skips** — return `Collections.unmodifiableSet(skips)` from `getSkips()`, add `getSkipCount()` method
+
+#### VoteSkipService
+1. **Synchronize vote-skip check** — ensure `addSkip` + threshold check is atomic (or accept eventual consistency and document it)
+
+### File Structure
+All changes in `src/main/java/me/bobert/netneutrality/music/`:
+- **Modified:** `QueueManager.java`, `TrackScheduler.java`, `TrackInfo.java`, `VoteSkipService.java`
+- **New:** `StuckTrackRecoveryHandler.java`
+- **New tests:** `src/test/java/me/bobert/netneutrality/command/music/QueueManagerTest.java`, `TrackSchedulerTest.java`, `TrackInfoTest.java`, `VoteSkipServiceTest.java`
+
+# Testing
+
+### Validation Approach
+Add unit tests for all four classes using JUnit 5 and Mockito (already in project dependencies via the existing test classes).
+
+### Key Scenarios
+- **QueueManager:** queue/dequeue ordering, skip single/multiple, shuffle preserves current track, removeFromQueue bounds, clearQueue idempotency, removeTracksFromUser correctness
+- **TrackInfo:** skip vote tracking, duplicate skip prevention, unmodifiable skips set, equals/hashCode
+- **VoteSkipService:** threshold calculation, skip when below min members, vote counting, duplicate vote handling
+- **TrackScheduler:** onTrackEnd triggers correct queue action per end reason, onTrackStuck recovery flow
+
+### Edge Cases
+- Queue with single track: skip, shuffle, remove
+- Skip count exceeding queue size
+- Empty queue operations
+- Concurrent vote-skip from same user
+
+# Delivery Steps
+
+### ✓ Step 1: Fix TrackInfo issues
+TrackInfo has correct logger, clean copyright, and encapsulated skip state.
+
+- Fix logger from `QueueManager.class` to `TrackInfo.class` (line 26)
+- Remove duplicate copyright block (lines 7-11)
+- Change `getSkips()` to return `Collections.unmodifiableSet(skips)`
+- Add `getSkipCount()` convenience method
+- Add `TrackInfoTest.java` covering skip tracking, duplicate prevention, equals/hashCode, and unmodifiable set enforcement
+
+### ✓ Step 2: Fix QueueManager thread-safety and queue logic
+QueueManager has correct synchronization and simplified queue insertion.
+
+- Remove all outer unsynchronized pre-checks in `clearQueue()`, `skip()`, `shuffle()`, `removeFromQueue()`, `removeTracksFromUser()` — consolidate into single synchronized blocks
+- Rewrite `queue(AudioTrack, Member)` to eliminate the confusing `addFirst`/`add` dual-path: simply add to tail, then start playback if nothing is playing
+- Fix `clearQueue()` to call `callback.onQueueEmpty()` only after confirming queue was non-empty
+- Fix `skip(int)` to skip all remaining when `nbTrack > queue.size()` instead of silently resetting to 1
+- Fix `removeTracksFromUser()` to do all filtering inside synchronized block
+- Add `QueueManagerTest.java` covering queue ordering, skip, shuffle, remove, clear, and edge cases
+
+### ✓ Step 3: Extract stuck-track recovery and fix TrackScheduler thread-safety
+TrackScheduler is simplified with extracted recovery logic and thread-safe context access.
+
+- Create `StuckTrackRecoveryHandler.java` encapsulating the retry-or-skip logic currently in `onTrackStuck()` (lines 129-173)
+- Simplify `onTrackStuck()` to delegate to the new handler
+- Reset `lastStuckTrack` in `onTrackStart()` to prevent stale state
+- Synchronize `getContext()` and `getDj()` methods (or make `context` volatile)
+- Add `TrackSchedulerTest.java` covering onTrackEnd behavior per end reason and stuck-track recovery delegation
+
+### ✓ Step 4: Improve VoteSkipService robustness and add tests
+VoteSkipService has documented concurrency behavior and full test coverage.
+
+- Add documentation comment about the vote-then-check atomicity assumption
+- Add `VoteSkipServiceTest.java` covering: threshold math, auto-skip below min members, vote accumulation, duplicate vote from same user, skip trigger when threshold exceeded

.junie/plans/remove-settings-singleton.md

@@ -0,0 +1,91 @@
+---
+sessionId: session-260909-154047-1h6n
+---
+
+# Requirements
+
+### Overview & Goals
+Remove the singleton pattern from `Settings` so it becomes a plain instantiable class. All access should go through constructor injection of `SettingsProvider`, except for the single bootstrap site in `App.main()` which creates the instance.
+
+### Scope
+**In Scope:**
+- Remove `static INSTANCE` field and `getInstance()` from `Settings`
+- Remove static helper methods `getDiscordInvite()` and `getVersion()` from `Settings`
+- Migrate all remaining `Settings.getInstance()` call sites to use injected `SettingsProvider`
+- Update the test to construct `Settings` directly
+
+**Out of Scope:**
+- Changing the `SettingsProvider` interface
+- Introducing a DI framework
+- Changing how properties are loaded
+
+# Technical Design
+
+### Current Implementation
+- `Settings` is a lazy singleton (`getInstance()`) implementing `SettingsProvider`
+- `SettingsProvider` interface already exists and is injected into most classes via `ApplicationContext`
+- `App.buildContext()` already registers the Settings instance as `SettingsProvider` in the context
+- **Remaining direct singleton usages (9 call sites):**
+  - `App.java` — `VERSION` static field (line 51), `main()` bootstrap (lines 61-62), `startup()` (line 89), `buildContext()` (line 112), `initJDA()` (line 190)
+  - `CommandContext.java` — `isMessageFromCreator()` (line 134)
+  - `WebModule.java` — `createRequest()` (line 289) via `Settings.getVersion()`
+  - `ReportBug.java` — `executeTask()` (line 34) via `Settings.getDiscordInvite()`
+  - `SettingsTest.java` — `getMavenVersion()` test (line 17)
+
+### Proposed Changes
+
+#### 1. `Settings.java`
+- Make constructor `public`
+- Remove `static INSTANCE` field, `getInstance()`, `getDiscordInvite()`, `getVersion()`
+- Keep `getMavenVersion()` as an instance method
+- Add `getDiscordInvite()` as an instance method on `SettingsProvider` (or keep it as a convenience on `Settings`)
+
+#### 2. `App.java`
+- Create `Settings` via `new Settings()` at the top of `main()`; pass it into `App` constructor or store as a field
+- Replace `VERSION` static field with an instance field initialized from the settings instance
+- Thread the `SettingsProvider` through `startup()`, `buildContext()`, `initJDA()`
+
+#### 3. `CommandContext.java`
+- Add a `SettingsProvider` field, accept it via constructor parameter
+- Update `isMessageFromCreator()` to use the injected provider
+- Update subclasses (`MessageCommandContext`, `SlashCommandContext`, etc.) to pass it through
+
+#### 4. `WebModule.java`
+- Accept a version string or `SettingsProvider` in the `Builder`; replace `Settings.getVersion()` call
+
+#### 5. `ReportBug.java`
+- Accept `SettingsProvider` via constructor injection; replace `Settings.getDiscordInvite()` with `settings.get("NETNEUTRALITY_BOT_INVITE", ...)`
+
+#### 6. `SettingsTest.java`
+- Use `new Settings()` instead of `Settings.getInstance()`
+
+### Risks
+- `CommandContext` is abstract with multiple subclasses — all constructors need updating
+- `WebModule.Builder` is used in many places including inside `Settings.getGitVersion()` itself — the version string approach (pass a `String` rather than the full provider) keeps this simpler
+
+# Delivery Steps
+
+### ✓ Step 1: Remove singleton from Settings class
+Settings can be instantiated with `new Settings()` and no longer holds static state.
+
+- Make the `Settings` constructor `public`
+- Remove the `static INSTANCE` field and `getInstance()` method
+- Remove static helpers `getDiscordInvite()` and `getVersion()`
+- Move `getDiscordInvite()` logic to an instance method (or inline at call sites)
+- Keep `getMavenVersion()` as-is (already instance method)
+
+### ✓ Step 2: Migrate App.java bootstrap to explicit instantiation
+App creates and threads a single Settings instance through its lifecycle methods.
+
+- Create `new Settings()` at the start of `main()` and store as a field on `App`
+- Replace `Settings.getInstance()` calls in `main()`, `startup()`, `buildContext()`, `initJDA()` with the field
+- Replace the `VERSION` static field with an instance field or a local derived from the settings instance
+
+### ✓ Step 3: Inject SettingsProvider into remaining call sites
+CommandContext, WebModule, and ReportBug no longer reach for the singleton.
+
+- Add `SettingsProvider` constructor parameter to `CommandContext`; update `isMessageFromCreator()` to use it
+- Update `CommandContext` subclasses (`MessageCommandContext`, `SlashCommandContext`, etc.) to pass the provider through
+- In `WebModule.Builder`, accept a version string parameter; replace `Settings.getVersion()` in `createRequest()`
+- In `ReportBug`, add `SettingsProvider` constructor parameter; replace `Settings.getDiscordInvite()` with `settings.get(...)`
+- Update `SettingsTest` to use `new Settings()` directly

.junie/plans/revert-package-structure.md

@@ -0,0 +1,214 @@
+---
+sessionId: session-260905-145156-xyio
+---
+
+# Requirements
+
+### Overview & Goals
+
+Revise the package structure section of the lifecycle refactor plan to use a hybrid layout that keeps the new `bootstrap/` package but reverts the rest to the familiar old-style naming and organization.
+
+### Scope
+
+**In Scope**
+- Reverting `framework/` → `core/` (engine: command, context, task machinery)
+- Reverting `platform/` hierarchy → flat old-style packages: `db/` (persistence + entities + repositories + services), `hooks/` (events), `http/` (web API), `music/` (music domain)
+- Reverting `feature/` vertical grouping → separate top-level `command/`, `tasks/`, `context/` packages with subcategory folders (e.g. `command/music/`, `tasks/scheduled/`)
+- Restoring `utils/` for remaining helpers (Settings, JpaUtils, MusicUtils, ChannelMessagePurger)
+- Keeping `bootstrap/` (ApplicationContext, Lifecycle, BotState, ReflectionHelper) — this is new and stays
+- Keeping `exceptions/` — unchanged
+- Keeping `shared/util/` (ContextUtils, GuildUtils, MessageFunction, MiscUtils, UserFunction)
+
+**Out of Scope**
+- Any behavioral or DI/lifecycle logic changes — this is purely a package restructure
+- Changing the DI refactor plan's other sections (Lifecycle contract, ApplicationContext, constructor injection, interfaces)
+
+### Target Layout
+
+```
+me.bobert.netneutrality
+├── App.java
+├── bootstrap/                  # NEW — keep as-is
+│   ├── ApplicationContext.java
+│   ├── BotState.java
+│   ├── Lifecycle.java
+│   └── ReflectionHelper.java
+├── core/                       # was framework/ → revert to core/
+│   ├── command/                # Command, CommandProcessor, CommandRegistry, CommandManager, options/, impl/
+│   ├── context/                # Context hierarchy, abstract bases
+│   └── tasks/                  # Task, TaskManager, StepTask, PersistableTask, persistence/, trait/, impl/
+├── command/                    # concrete command implementations (was feature/*/command/)
+│   ├── admin/
+│   ├── basic/
+│   ├── bot/
+│   ├── crypto/
+│   ├── custom/
+│   ├── git/
+│   ├── music/
+│   └── react/
+├── context/                    # concrete context implementations (was framework/context/command/ + task/)
+│   ├── command/
+│   ├── tasks/
+│   └── MusicChannelContext.java
+├── tasks/                      # concrete task implementations (was feature/*/task/)
+│   ├── emoji/
+│   ├── generic/
+│   ├── git/
+│   ├── help/
+│   ├── music/
+│   ├── reaction/
+│   └── scheduled/
+├── db/                         # persistence model (was data/ + platform/persistence/)
+│   ├── entities/               # O* entities
+│   ├── repository/
+│   ├── service/                # GuildService, GuildServiceProvider, BlacklistService, etc.
+│   ├── GSettings.java
+│   ├── Repository.java
+│   ├── DatabaseMigration.java
+│   ├── SessionManager.java     # SessionProvider impl
+│   └── JpaUtils.java
+├── hooks/                      # was platform/event/
+│   └── EventsHandler.java
+├── http/                       # was platform/web/
+│   ├── server/
+│   └── WebModule.java
+├── music/                      # music domain (was feature/music/ minus commands/tasks)
+│   ├── AudioPlayerSendHandler.java
+│   ├── MusicManager.java
+│   ├── MusicService.java
+│   ├── QueueManager.java
+│   ├── SourceFinder.java
+│   ├── source/
+│   ├── TrackInfo.java
+│   ├── TrackLoadingHandler.java
+│   └── TrackScheduler.java
+├── utils/                      # remaining helpers not in shared/util/
+│   ├── Settings.java           # SettingsProvider impl
+│   ├── ChannelMessagePurger.java
+│   ├── JpaUtils.java           # (or in db/, see note)
+│   └── MusicUtils.java
+├── shared/util/                # NEW — keep as-is
+│   ├── ContextUtils.java
+│   ├── GuildUtils.java
+│   ├── MessageFunction.java
+│   ├── MiscUtils.java
+│   └── UserFunction.java
+├── exceptions/                 # unchanged
+└── core/thread/ OR thread/     # ThreadManager, ScheduledTaskManager, BaseThreadFactory
+```
+
+**Note:** `core/thread/` was the old location for threading. The old layout also had a top-level `thread/` for `MusicManagerCleanupThread`. Both can be restored as they were.
+
+### Key Moves (current → proposed)
+
+| Current (new) | Proposed (hybrid) |
+|---|---|
+| `framework/command/` | `core/command/` |
+| `framework/context/` | `core/context/` |
+| `framework/task/` | `core/tasks/` |
+| `framework/NetNeutralityBot.java` | remove or merge into App |
+| `platform/config/Settings.java` | `utils/Settings.java` |
+| `platform/persistence/*` | `db/` (SessionManager, DatabaseMigration, JpaUtils, Repository) |
+| `platform/concurrency/*` | `core/thread/` |
+| `platform/logging/LogHandler.java` | `core/LogHandler.java` |
+| `platform/event/EventsHandler.java` | `hooks/EventsHandler.java` |
+| `platform/web/*` | `http/*` |
+| `data/entity/` | `db/entities/` |
+| `data/repository/` | `db/repository/` |
+| `data/service/` | `db/service/` |
+| `feature/music/command/*` | `command/music/` |
+| `feature/music/*.java` (domain) | `music/` |
+| `feature/moderation/command/*` | `command/admin/` |
+| `feature/moderation/ChannelMessagePurger.java` | `utils/ChannelMessagePurger.java` |
+| `feature/reaction/command/*` | `command/react/` |
+| `feature/reaction/task/*` | `tasks/reaction/` |
+| `feature/git/command/*` | `command/git/` |
+| `feature/git/task/*` | `tasks/git/` |
+| `feature/crypto/command/*` | `command/crypto/` |
+| `feature/help/command/*` | `command/basic/` + `command/bot/` |
+| `feature/help/task/*` | `tasks/help/` |
+| `feature/custom/command/*` | `command/custom/` |
+| `bootstrap/` | `bootstrap/` (no change) |
+| `shared/util/` | `shared/util/` (no change) |
+| `exceptions/` | `exceptions/` (no change) |
+
+# Technical Design
+
+### Current Implementation
+
+The codebase currently uses the post-refactor layout with:
+- `bootstrap/` — ApplicationContext, Lifecycle, BotState, ReflectionHelper
+- `framework/` — command, context, task engine
+- `platform/` — config, persistence, concurrency, logging, event, web
+- `feature/` — music, moderation, reaction, git, crypto, help, custom (feature-vertical grouping)
+- `data/` — entity, repository, service
+- `shared/util/` — cross-cutting helpers
+- `exceptions/`
+
+All DI/lifecycle wiring (constructor injection, interfaces like `SettingsProvider`, `SessionProvider`, `ExecutorProvider`, `CommandRegistry`, `TaskManager`, `MusicService`, `GuildServiceProvider`) remains intact — only package locations change.
+
+### Key Decisions
+1. **Revert engine package name**: `framework/` → `core/` — matches the original naming the team is familiar with.
+2. **Flatten infrastructure**: dissolve `platform/` hierarchy back to `db/`, `hooks/`, `http/`, `core/thread/`, `utils/` — removes the extra nesting that added cognitive overhead.
+3. **Separate top-level command/tasks/context**: undo feature-vertical grouping in `feature/` — concrete implementations go back to `command/<category>/`, `tasks/<category>/`, `context/` as before.
+4. **Keep bootstrap/ and shared/util/**: these are genuinely new and useful additions with no old equivalent.
+5. **Restore `db/entities/`**: revert `data/entity/` back to `db/entities/` (plural, matching old convention).
+6. **Service interfaces stay**: `SettingsProvider`, `SessionProvider`, `ExecutorProvider`, etc. remain — they just live in their reverted package locations (e.g. `SettingsProvider` in `utils/` alongside `Settings`).
+
+### Proposed Changes
+
+This is a pure move/rename refactor using IDE safe "Move Class" operations. No logic changes. The DI wiring, lifecycle priorities, constructor injection, and all interfaces remain exactly as they are — only their package declarations and import statements change.
+
+### Risks
+- **Import churn** — same risk as the original restructure; mitigated by IDE "Move Class" refactor, one subsystem at a time, build after each.
+- **Interface co-location** — service interfaces (e.g. `SessionProvider`) now live alongside their impls in `db/` or `utils/` rather than in a separate `platform/` package. This is acceptable for this project's size.
+
+# Delivery Steps
+
+### ✓ Step 1: Move engine packages from framework/ back to core/
+The `framework/` package is renamed back to `core/` with its original subpackage names.
+
+- Move `framework/command/` → `core/command/` (all engine classes: Command, CommandProcessor, CommandRegistry, CommandManager, CommandCategory, CommandContainer, CommandExecutionResult, CommandOptionsBuilder, impl/, options/)
+- Move `framework/context/` → `core/context/` (Context, AbstractContext, CommandContext, TaskContext, InteractionContext, MessageContext, NoMessageContext, AsyncContext)
+- Move `framework/task/` → `core/tasks/` (Task, TaskManager interface + impl, StepTask, PersistableTask, BuiltInTask, ScheduledTask, TaskCleanup, persistence/, trait/, impl/, generic/)
+- Move `framework/NetNeutralityBot.java` into `core/` or merge into App if it's just a shell
+- Move `platform/logging/LogHandler.java` → `core/LogHandler.java`
+- Move `platform/concurrency/*` → `core/thread/` (ThreadManager/ExecutorProvider, ScheduledTaskManager, BaseThreadFactory)
+- Update all imports; verify build with `./mvnw compile`
+
+### ✓ Step 2: Move persistence and infrastructure packages back to db/, hooks/, http/, utils/
+Infrastructure packages are flattened back to their original top-level locations.
+
+- Move `data/entity/` → `db/entities/` (restore plural naming)
+- Move `data/repository/` → `db/repository/`
+- Move `data/service/` → `db/service/` (GuildService, GuildServiceProvider, GuildSettingService, BlacklistService, TaskService)
+- Move `data/GSettings.java` → `db/GSettings.java`
+- Move `platform/persistence/` contents → `db/` (SessionManager/SessionProvider, DatabaseMigration, Repository, JpaUtils, SessionProvider interface)
+- Move `platform/config/Settings.java` + `SettingsProvider` → `utils/`
+- Move `platform/event/EventsHandler.java` → `hooks/EventsHandler.java`
+- Move `platform/web/` → `http/` (WebApi, server/, WebModule)
+- Move `feature/moderation/ChannelMessagePurger.java` → `utils/ChannelMessagePurger.java`
+- Move `feature/music/MusicUtils.java` → `utils/MusicUtils.java` (if it exists)
+- Delete empty `platform/` and `data/` directories
+- Update all imports; verify build with `./mvnw compile`
+
+### ✓ Step 3: Restore music domain package and split feature/ into command/, tasks/, context/
+Feature-vertical grouping is dissolved back into separate top-level packages.
+
+- Move `feature/music/` domain classes (MusicManager, MusicService, QueueManager, AudioPlayerSendHandler, SourceFinder, source/, TrackInfo, TrackLoadingHandler, TrackScheduler, MusicChannelContext) → `music/`
+- Move concrete context classes from `framework/context/command/` → `context/command/` and `framework/context/task/` → `context/tasks/`; move MusicChannelContext → `context/MusicChannelContext.java`
+- Move `feature/music/command/*` → `command/music/`
+- Move `feature/moderation/command/*` → `command/admin/`
+- Move `feature/reaction/command/*` → `command/react/`
+- Move `feature/git/command/*` → `command/git/`
+- Move `feature/crypto/command/*` → `command/crypto/`
+- Move `feature/help/command/*` → `command/basic/` and `command/bot/` (matching old categorization)
+- Move `feature/custom/command/*` → `command/custom/`
+- Move `feature/reaction/task/*` → `tasks/reaction/`
+- Move `feature/git/task/*` → `tasks/git/`
+- Move `feature/help/task/*` → `tasks/help/`
+- Move `feature/music/task/*` → `tasks/music/`
+- Move scheduled tasks → `tasks/scheduled/`
+- Delete empty `feature/` directory
+- Update all imports; verify full build with `./mvnw package`
+- Update `docs/architecture.md` package map table to reflect the new hybrid layout

.junie/plans/thread-safety-improvements.md

@@ -0,0 +1,99 @@
+---
+sessionId: session-260910-054543-zckm
+---
+
+# Requirements
+
+### Overview & Goals
+Analyze and fix thread-safety issues and improve the `ExecutorProvider` / `ThreadManager` infrastructure and all code that interacts with it.
+
+### Scope
+#### In Scope
+- Fix thread-safety bugs in `ThreadManager`, `TaskManagerImpl`, `ChannelMessagePurger`, `MusicManager`
+- Improve executor pool configuration (bounded pools, proper shutdown)
+- Clean up inconsistent synchronization patterns
+
+#### Out of Scope
+- Rewriting the task/command architecture
+- Changing the `QueueManager` synchronization (it's consistent and correct, just verbose)
+
+# Technical Design
+
+### Current Issues Found
+
+#### 1. `ThreadManager` (`core/thread/ThreadManager.java`)
+- **Unbounded cached thread pools** — `newCachedThreadPool()` creates unlimited threads; under load (e.g., many guilds purging simultaneously) this can exhaust memory.
+- **Shutdown bug (line 66-69)** — If `awaitTermination` throws `InterruptedException` on the *first* executor, the `catch` block exits the loop and remaining executors only get `shutdownNow()` without a prior `shutdown()` call. Each executor should be shut down independently.
+- **No daemon threads** — `BaseThreadFactory` doesn't set `thread.setDaemon(true)`, so leaked threads can prevent JVM exit.
+
+#### 2. `TaskManagerImpl` (`core/tasks/TaskManagerImpl.java`)
+- **Null values in `ConcurrentHashMap` (line 178-184)** — `computeIfAbsent` returns `null` for `PersistableTask`/`BuiltInTask`, but `ConcurrentHashMap` does **not** permit null values. This will throw `NullPointerException` at runtime.
+- **Mixed synchronization** — `getTasks()` is `synchronized` on `this`, but all mutations use `ConcurrentHashMap` operations (no `synchronized`). The `synchronized` keyword on `getTasks()` provides no actual protection since `insert()`, `removeTask()`, etc. don't synchronize on `this`.
+- **`hasTask()` race (line 93-95)** — Check-then-act across two collections (`tasks` and `pendingTasks`) without synchronization.
+- **`handle()` lock cleanup race (line 191-194)** — After acquiring the lock, it checks `tasks.containsKey()` and removes from `tasksLock`, but another thread could be waiting on the same lock and will find it removed.
+
+#### 3. `ChannelMessagePurger` (`utils/ChannelMessagePurger.java`)
+- **Double unlock bug** — `purgeMessages()` acquires `lock` via `tryLock()` (line 68) and releases it in `finally` (line 79). But `safePurge()` also calls `lock.unlock()` (line 154), causing an `IllegalMonitorStateException` or releasing a lock that a *different* thread now holds.
+- **Non-thread-safe static `HashMap`** (line 40) — `instances` is a plain `HashMap` accessed from multiple threads via `computeIfAbsent`. Should be `ConcurrentHashMap`.
+- **Static mutable `ExecutorProvider` binding** — The `volatile` field + `bind()` pattern works but is fragile; a null check race exists between `canLockBeAcquired` callers and `purgeMessages`.
+
+#### 4. `MusicManager` (`music/MusicManager.java`)
+- **Inconsistent synchronization** — `isConnected()`, `connect()`, `disconnect()`, `play()` are `synchronized`, but `isCurrentlyPlaying()` (line 114), `getCurrentlyPlaying()` (line 110), `stopTrack()` (line 138), `resume()` (line 142) are not. If these are called from event threads concurrently with `disconnect()`, they can see stale state.
+
+#### 5. `BaseThreadFactory` (`core/thread/BaseThreadFactory.java`)
+- Threads are not set as daemon threads, which can prevent clean JVM shutdown if an executor leaks.
+
+### Proposed Changes
+
+#### `ThreadManager`
+- Replace `newCachedThreadPool()` with `newFixedThreadPool()` or a bounded `ThreadPoolExecutor` with a reasonable max (e.g., `availableProcessors() * 2`).
+- Fix shutdown loop: wrap each executor's `shutdown()`/`awaitTermination()` in its own try-catch so one failure doesn't skip the rest.
+- Consider adding a `getExecutorStatus()` method for observability.
+
+#### `BaseThreadFactory`
+- Set `thread.setDaemon(true)` to prevent JVM hang on unclean shutdown.
+
+#### `TaskManagerImpl`
+- Fix `computeIfAbsent` null return: use a sentinel or simply don't store an entry for tasks that don't need locking (use `get()` + null check instead).
+- Remove misleading `synchronized` on `getTasks()` or make all task mutations consistently synchronized.
+- Guard `hasTask()` with proper synchronization or accept eventual consistency and document it.
+- Fix lock cleanup race in `handle()` — don't remove from `tasksLock` inside the lock-held section; let `removeTask()` handle cleanup.
+
+#### `ChannelMessagePurger`
+- Remove the `lock.unlock()` call on line 154 inside `safePurge()` — the `finally` block in `purgeMessages()` already handles it.
+- Change `instances` from `HashMap` to `ConcurrentHashMap`.
+
+#### `MusicManager`
+- Either synchronize all public methods that touch `player`/`AudioManager` state, or remove `synchronized` from methods where JDA already guarantees thread safety and document the threading model.
+
+# Delivery Steps
+
+### ✓ Step 1: Fix ThreadManager and BaseThreadFactory
+ThreadManager uses bounded pools and has correct shutdown; BaseThreadFactory produces daemon threads.
+
+- Replace `Executors.newCachedThreadPool()` in `ThreadManager.getExecutor()` with a bounded `ThreadPoolExecutor` (core=0, max=availableProcessors*2, 60s keepAlive, LinkedBlockingQueue).
+- Fix `stop()` shutdown loop: wrap each executor's `shutdown()`+`awaitTermination()` in its own try-catch so an `InterruptedException` on one executor doesn't skip the rest.
+- In `BaseThreadFactory.newThread()`, add `thread.setDaemon(true)`.
+- Verify the `getScheduledExecutor()` pool size is still appropriate.
+
+### ✓ Step 2: Fix TaskManagerImpl thread-safety bugs
+TaskManagerImpl has no null-in-ConcurrentHashMap violations and consistent synchronization.
+
+- Replace the `computeIfAbsent` that returns null (line 178-184) with a pattern that avoids storing null: check task type first, only call `computeIfAbsent` when a lock is actually needed.
+- Remove the misleading `synchronized` keyword from `getTasks()`, or switch to a consistent locking strategy across all mutation methods.
+- Fix the lock cleanup race in `handle()`: do not remove from `tasksLock` at line 193; let `removeTask()` be the sole owner of lock cleanup.
+- Document the threading contract for `hasTask()` (check-then-act across two collections is inherently racy).
+
+### ✓ Step 3: Fix ChannelMessagePurger concurrency bugs
+ChannelMessagePurger has no double-unlock and uses thread-safe collections.
+
+- Remove the redundant `lock.unlock()` call on line 154 in `safePurge()` — the `finally` block in `purgeMessages()` (line 79) already releases the lock.
+- Change the static `instances` field (line 40) from `HashMap` to `ConcurrentHashMap`.
+- Remove the `synchronized` keyword from `countAllChannelMessages()` and `safePurge()` since the `ReentrantLock` already provides mutual exclusion.
+
+### ✓ Step 4: Harmonize MusicManager synchronization
+MusicManager has a consistent and documented threading model.
+
+- Add `synchronized` to `isCurrentlyPlaying()`, `getCurrentlyPlaying()`, `stopTrack()`, and `resume()` to match the existing pattern on `connect()`/`disconnect()`/`play()`.
+- Alternatively, if JDA's `AudioPlayer` is already thread-safe, remove `synchronized` from all methods and add a class-level Javadoc explaining the threading model.
+- Investigate which approach is correct by checking Lavaplayer's `AudioPlayer` thread-safety guarantees, then apply consistently.

.mvn/wrapper/maven-wrapper.properties

@@ -1,18 +1,3 @@
-# Licensed to the Apache Software Foundation (ASF) under one
+wrapperVersion=3.3.4
-# or more contributor license agreements.  See the NOTICE file
+distributionType=only-script
-# distributed with this work for additional information
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.15/apache-maven-3.9.15-bin.zip
-# regarding copyright ownership.  The ASF licenses this file
-# to you under the Apache License, Version 2.0 (the
-# "License"); you may not use this file except in compliance
-# with the License.  You may obtain a copy of the License at
-#
-#   http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing,
-# software distributed under the License is distributed on an
-# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-# KIND, either express or implied.  See the License for the
-# specific language governing permissions and limitations
-# under the License.
-distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.6/apache-maven-3.9.6-bin.zip
-wrapperUrl=https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.2.0/maven-wrapper-3.2.0.jar

Dockerfile

@@ -1,17 +1,6 @@
-FROM eclipse-temurin:17-jdk-alpine AS build
+FROM eclipse-temurin:25-jre@sha256:ff82c74a630c08b417502c4c18189e62074edbb28eb1f2d31b799ac138c01058
 
-COPY .mvn/ .mvn
+RUN apt-get update && apt-get install -y --no-install-recommends netcat-openbsd curl && rm -rf /var/lib/apt/lists/*
-COPY mvnw pom.xml ./
-COPY src ./src
-
-RUN ["chmod", "+x", "./mvnw"]
-RUN ./mvnw install
-
-
-FROM eclipse-temurin:17-jre-alpine
-
-RUN apk add netcat-openbsd
-RUN apk add curl
 
 WORKDIR /app
 
@@ -19,7 +8,7 @@ ARG API_PORT=9000
 EXPOSE ${API_PORT}
 
 COPY startup.sh ./
-COPY --from=build /target/netneutrality-jar-with-dependencies.jar ./
+COPY target/netneutrality.jar ./
 
 RUN ["chmod", "+x", "./startup.sh"]
 CMD ["./startup.sh"]

bot.properties.example

@@ -1,17 +1,24 @@
+NETNEUTRALITY_TAG=latest
+
 NETNEUTRALITY_BOT_ENV=dev
 NETNEUTRALITY_BOT_TOKEN=
-NETNEUTRALITY_BOT_PREFIX=
+NETNEUTRALITY_BOT_PREFIX=$
 NETNEUTRALITY_BOT_OWNER=
+NETNEUTRALITY_BOT_INVITE=
 NETNEUTRALITY_API_PORT=9000
 
 MYSQL_HOST=127.0.0.1
-MYSQL_USER=root
-MYSQL_PASSWORD=
-MYSQL_DATABASE=
 MYSQL_PORT=3306
+MYSQL_USER=java
+MYSQL_PASSWORD=password
+MYSQL_DATABASE=netneutrality
+MYSQL_ROOT_PASSWORD=password
+MARIADB_AUTO_UPGRADE=1
 
 NETNEUTRALITY_PO_TOKEN=
 NETNEUTRALITY_VISITOR_DATA=
+NETNEUTRALITY_CIPHER_URL=http://localhost:8001
+NETNEUTRALITY_CIPHER_PASSWORD=
 
 NETNEUTRALITY_SENTRY_DSN=
 GITLAB_HOST=

checkstyle.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0"?>
+<!DOCTYPE module PUBLIC
+        "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
+        "https://checkstyle.org/dtds/configuration_1_3.dtd">
+
+<module name="Checker">
+    <property name="severity" value="warning"/>
+
+    <!-- Allows tab characters -->
+    <module name="FileTabCharacter">
+        <property name="eachLine" value="false"/>
+    </module>
+
+    <module name="TreeWalker">
+        <!-- Indentation with tabs -->
+        <module name="Indentation">
+            <property name="basicOffset" value="4"/>
+            <property name="tabWidth" value="4"/>
+            <property name="forceStrictCondition" value="false"/>
+        </module>
+
+        <!-- Common useful checks -->
+        <module name="EmptyBlock">
+            <property name="option" value="text"/>
+        </module>
+        <module name="NeedBraces"/>
+        <module name="AvoidStarImport"/>
+        <module name="UnusedImports"/>
+        <module name="EqualsHashCode"/>
+
+        <!-- Relaxed Javadoc rules -->
+        <module name="JavadocMethod">
+            <property name="allowMissingParamTags" value="true"/>
+            <property name="allowMissingReturnTag" value="true"/>
+        </module>
+    </module>
+</module>

docker-compose-webapp.yml

@@ -1,64 +0,0 @@
-services:
-  db:
-    image: mariadb:lts
-    container_name: db
-    restart: unless-stopped
-    volumes:
-      - netneutrality-db:/var/lib/mysql
-      - ./sql:/docker-entrypoint-initdb.d
-    environment:
-      MYSQL_USER: 'java'
-      MYSQL_PASSWORD: 'password'
-      MYSQL_DATABASE: 'netneutrality'
-      MYSQL_ROOT_PASSWORD: 'password'
-      MARIADB_AUTO_UPGRADE: '1'
-    ports:
-      - "3306"
-    networks:
-      - internal
-
-  bot:
-    container_name: bot
-    build: ./
-    restart: unless-stopped
-    depends_on:
-      - db
-    volumes:
-      - ./logs:/app/logs
-    environment:
-      MYSQL_HOST: 'db'
-      MYSQL_USER: 'java'
-      MYSQL_PASSWORD: 'password'
-      MYSQL_DATABASE: 'netneutrality'
-    ports:
-      - "9000:9000"
-    networks:
-      - internal
-
-  webapp:
-    image: bot-webapp:dev
-    build: ../netneutrality-webapp
-    restart: always
-    depends_on:
-      - db
-      - bot
-    volumes:
-      - ./logs:/app/logs
-    environment:
-      DB_CONNECTION: 'mysql'
-      DB_HOST: 'db'
-      DB_PORT: '3306'
-      DB_DATABASE: 'netneutrality'
-      DB_USERNAME: 'java'
-      DB_PASSWORD: 'password'
-      BOT_URL: 'http://bot:9000'
-    ports:
-      - '8080:80'
-    networks:
-      - internal
-
-volumes:
-  netneutrality-db:
-
-networks:
-  internal:

docker-compose.yml

@@ -1,44 +1,46 @@
 services:
-  db:
+  netneutrality-db:
-    image: mariadb:lts
+    image: mariadb:11@sha256:1cac8492bd78b1ec693238dc600be173397efd7b55eabc725abc281dc855b482
     container_name: db
     restart: unless-stopped
+    networks:
+      - netneutrality
     volumes:
       - netneutrality-db:/var/lib/mysql
-      - ./sql:/docker-entrypoint-initdb.d
     environment:
-      MYSQL_USER: 'java'
+      - MYSQL_USER=${MYSQL_USER:-java}
-      MYSQL_PASSWORD: 'password'
+      - MYSQL_PASSWORD=${MYSQL_PASSWORD:-password}
-      MYSQL_DATABASE: 'netneutrality'
+      - MYSQL_DATABASE=${MYSQL_DATABASE:-netneutrality}
-      MYSQL_ROOT_PASSWORD: 'password'
+      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD:-password}
-      MARIADB_AUTO_UPGRADE: '1'
+      - MARIADB_AUTO_UPGRADE=1
-    ports:
-      - "3306:3306"
-    networks:
-      - internal
 
-  bot:
+  netneutrality-bot:
+    image: gitea.bobert.me/anthorob/netneutrality:${NETNEUTRALITY_TAG:-latest}
     container_name: bot
-    build: ./
     restart: unless-stopped
+    env_file: .env
+    networks:
+      - netneutrality
     depends_on:
-      - db
+      - netneutrality-db
     volumes:
       - ./logs:/app/logs
     environment:
-      MYSQL_HOST: 'db'
+      MYSQL_HOST: netneutrality-db
-      MYSQL_PORT: '3306'
+      MYSQL_PORT: 3306
-      MYSQL_USER: 'java'
+      MYSQL_USER: java
-      MYSQL_PASSWORD: 'password'
+      MYSQL_PASSWORD: password
-      MYSQL_DATABASE: 'netneutrality'
+      MYSQL_DATABASE: netneutrality
-    env_file: ".env"
+  ejs-api:
-    ports:
+    image: ghcr.io/kikkia/yt-cipher:master@sha256:4c5ec381ff57336cfc24822d2b526a5ad7cd0171f61065a1bbc87bb736842449
-      - "9000:9000"
+    container_name: ejs_signature_api
+    restart: unless-stopped
     networks:
-      - internal
+      - netneutrality
-
+    # environment: # UNCOMMENT THIS LINE AND API_TOKEN TO ADD A PASSWORD
+    #   - API_TOKEN=test
 volumes:
-  netneutrality-db:
+  netneutrality-db: null
 
 networks:
-  internal:
+  netneutrality: null

docs/README.md

@@ -0,0 +1,37 @@
+# Net Neutrality — Technical Documentation
+
+This directory contains detailed technical documentation for the **Net Neutrality** Discord bot
+(`me.bobert:netneutrality`, version `3.0.0`).
+
+It is intended for developers working on the codebase. It documents every major system and
+subsystem, how they fit together, and the end-to-end flows that tie them.
+
+## Table of contents
+
+| Document | Subsystem |
+|---|---|
+| [architecture.md](architecture.md) | High-level architecture, startup/shutdown lifecycle, tech stack |
+| [events.md](events.md) | Event handling & routing (`EventsHandler`) |
+| [contexts.md](contexts.md) | Contexts — the abstraction over Discord events |
+| [commands.md](commands.md) | Commands — message & slash commands, dispatch, options |
+| [tasks.md](tasks.md) | Tasks — button/emoji/modal/step/built-in/persistable/scheduled tasks |
+| [persistence.md](persistence.md) | Database — Hibernate/JPA, Flyway, entities, repositories, services |
+| [music.md](music.md) | Music — Lavaplayer pipeline, queue, custom Udio source |
+| [web-api.md](web-api.md) | HTTP Web API — internal control & introspection server |
+| [threading.md](threading.md) | Threading & scheduling infrastructure |
+| [utilities-and-bootstrap.md](utilities-and-bootstrap.md) | Utilities, configuration, logging, exceptions |
+
+## How to read this documentation
+
+Start with [architecture.md](architecture.md) for the big picture and the startup sequence.
+Then read [events.md](events.md) and [contexts.md](contexts.md), because almost everything else
+is triggered through a **Context** produced by the **EventsHandler**. From there, the two primary
+execution paths are [commands.md](commands.md) and [tasks.md](tasks.md).
+
+## Conventions
+
+- Class names are given fully qualified on first mention, then by simple name.
+- Database entity classes are prefixed with `O` (e.g. `OGuild`), and are documented in
+  [persistence.md](persistence.md).
+- Environment variables / configuration keys use the `NETNEUTRALITY_*` and `MYSQL_*` prefixes and
+  are documented in [utilities-and-bootstrap.md](utilities-and-bootstrap.md).

docs/architecture.md

@@ -0,0 +1,161 @@
+# Architecture Overview
+
+Net Neutrality is a Java 25 Discord bot built on top of [JDA](https://github.com/discord-jda/JDA).
+It is packaged as a single fat JAR (via the Maven Shade plugin) whose entry point is
+`me.bobert.netneutrality.App`.
+
+## Big picture
+
+Discord sends **events** over the gateway. A single JDA `EventListener`
+(`me.bobert.netneutrality.hooks.EventsHandler`) receives every event and turns it into a
+**Context** — a high-level abstraction over that event. Each context is then routed to one of three
+execution paths:
+
+```
+                              ┌──────────────────────────────┐
+     Discord Gateway  ───────▶│        EventsHandler         │
+        (JDA events)          │  event class → Context factory│
+                              └───────────────┬──────────────┘
+                                              │ builds a Context
+                    ┌─────────────────────────┼───────────────────────────┐
+                    ▼                          ▼                           ▼
+            CommandContext              TaskContext                (no Context)
+                    │                          │                    lambda /
+                    ▼                          ▼                    consumer runs
+            CommandProcessor            TaskManager.handle()        directly
+            .dispatch()                 (lookup task by id)          (e.g. GuildJoin)
+                    │                          │
+                    ▼                          ▼
+             Command.execute()          Task.execute()
+```
+
+1. **Command flow** — the context is a `CommandContext`; it is handed to `CommandProcessor` which
+   resolves and runs a `Command`. See [commands.md](commands.md).
+2. **Task flow** — the context is a `TaskContext`; it is handed to `TaskManager` which looks up a
+   `Task` by its **id** and runs it. See [tasks.md](tasks.md).
+3. **Lambda flow** — for simple events (e.g. `GuildJoinEvent`, `GuildLeaveEvent`) a consumer runs
+   directly and no context is routed onward. See [events.md](events.md).
+
+Around this core are the supporting subsystems: [persistence](persistence.md) (Hibernate + Flyway),
+[music](music.md) (Lavaplayer), the [web API](web-api.md), and the [threading/scheduling](threading.md)
+infrastructure.
+
+## Technology stack
+
+| Concern | Library | Version |
+|---|---|---|
+| Discord API | `net.dv8tion:JDA` | 6.4.1 |
+| Voice / DAVE (E2EE) | `club.minnced:jdave-*` | 0.1.8 |
+| Audio engine | `dev.arbjerg:lavaplayer` | 2.2.6 |
+| YouTube source | `dev.lavalink.youtube:v2` | 1.18.2 |
+| ORM | `org.hibernate.orm:hibernate-core` | 7.1.9.Final |
+| Connection pool | `hibernate-hikaricp` (HikariCP) | 7.1.9.Final |
+| JDBC driver | `com.mysql:mysql-connector-j` | 9.7.0 |
+| DB migrations | `org.flywaydb:flyway-core` / `flyway-mysql` | 11.20.3 |
+| Error tracking | `io.sentry:sentry` | 8.41.0 |
+| GitLab integration | `org.gitlab4j:gitlab4j-api` | 6.2.0 |
+| HTTP client | `com.squareup.okhttp3:okhttp-jvm` | 5.3.2 |
+| JSON | `org.json:json` + `com.google.code.gson:gson` | — |
+| Classpath scanning | `org.reflections:reflections` | 0.10.2 |
+| Emoji parsing | `net.fellbaum:jemoji` | 1.7.6 |
+| Logging | Log4j2 + `log4j-slf4j2-impl` | 2.26.0 |
+| Testing | JUnit Jupiter 6 + Mockito 5 | — |
+
+The HTTP **server** for the internal API uses the JDK built-in
+`com.sun.net.httpserver.HttpServer` (no external framework); see [web-api.md](web-api.md).
+
+## Startup lifecycle
+
+The entry point is `App.main()` followed by the `App()` constructor which calls
+`startup()`. Bootstrap is driven by a hand-rolled
+[`ApplicationContext`](utilities-and-bootstrap.md#applicationcontext--lifecycle) that owns wired
+instances and starts every [`Lifecycle`](utilities-and-bootstrap.md#applicationcontext--lifecycle)
+component in ascending priority order.
+
+1. **Print banner / read env** — reads `NETNEUTRALITY_BOT_ENV` (default `dev`) via the early-bootstrap
+   `Settings.getInstance()` singleton (the only remaining process-wide settings access point; it is
+   also registered into the context as `SettingsProvider` for constructor injection).
+2. **Sentry** — if `NETNEUTRALITY_SENTRY_DSN` is set, initialize the Sentry SDK
+   (environment, release = `VERSION`, traces sample rate 1.0).
+3. **Log levels** — in `dev`, raise JDA / Lavalink-YouTube / sedmelluq logging to `DEBUG`.
+4. `startup()`:
+   1. Validate `NETNEUTRALITY_BOT_TOKEN` is present (throws if missing).
+   2. `buildContext()` — register domain services and lifecycle adapters (see priorities below).
+   3. `context.start()` — start every `Lifecycle` component in ascending priority order.
+   4. Register a JVM shutdown hook calling `shutdown()` → `context.stop()`.
+
+### Lifecycle priorities (startup order)
+
+| Priority | Component | What `start()` does |
+|---|---|---|
+| 10 | `SessionManager` (`SessionProvider`) | Build Hibernate `SessionFactory` + run Flyway migrations. Binds itself into `JpaUtils`. |
+| 20 | `ThreadManager` (`ExecutorProvider`) | No-op start (executors are lazy). Bound into `ChannelMessagePurger`. |
+| 30 | `CommandManager` (`CommandRegistry`) | Reflectively discover/register `Command` implementations with context-aware constructor injection. |
+| 30 | `TaskManagerImpl` (`TaskManager`) | Reflectively load built-in & scheduled tasks (DI) and reload persistable tasks from the DB. |
+| 40 | `MusicServiceImpl` (`MusicService`) | Initialise the shared Lavaplayer `AudioPlayerManager`. |
+| 55 | `ScheduledTaskManager` | No-op start (tasks are scheduled by `TaskManager` during its own start). |
+| 60 | JDA adapter | Build `JDA` with gateway intents and await ready. |
+| 65 | Post-JDA adapter | Register slash commands, attach `EventsHandler` (injected providers), set presence. |
+| 70 | `WebApi` | Start the internal HTTP server (`NETNEUTRALITY_API_PORT`, default 9000). |
+
+Commands and tasks that need shared services declare them as constructor parameters
+(`MusicService`, `TaskManager`, `GuildServiceProvider`, `SettingsProvider`, `CommandRegistry`, …).
+`ReflectionHelper` picks the richest public constructor whose parameter types all resolve from the
+context (falling back to a no-arg constructor when none match).
+
+### Gateway intents
+
+`initJDA()` enables: `GUILD_MEMBERS`, `GUILD_MESSAGE_REACTIONS`, `GUILD_VOICE_STATES`,
+`MESSAGE_CONTENT`. It also installs the DAVE (end-to-end encrypted voice) session factory via
+`AudioModuleConfig().withDaveSessionFactory(new JDaveSessionFactory())`.
+
+## Shutdown lifecycle
+
+`App.shutdown()` (invoked by the JVM shutdown hook, `ShutdownCommand`, or the HTTP
+`/actions/shutdown` endpoint) calls `context.stop()`, which stops every registered `Lifecycle`
+component in the **exact reverse** of start order. Failures in one component are logged and do not
+block the others. Effectively this means:
+
+1. `WebApi.stop()` — stop the HTTP server and its executor.
+2. Post-JDA adapter — no-op.
+3. JDA adapter — `jda.shutdown()`.
+4. `ScheduledTaskManager.stop()` — cancel all scheduled tasks.
+5. `MusicServiceImpl.stop()` — disconnect players / leave voice channels.
+6. `CommandManager` / `TaskManagerImpl` — no-op stop today.
+7. `ThreadManager.stop()` — shut down the shared executors.
+8. `SessionManager.stop()` — release the Hibernate registry / connection pool.
+
+## Configuration & build
+
+- **Config sources** — `Settings` loads `bot.properties` and overlays environment variables (env
+  vars win). See [utilities-and-bootstrap.md](utilities-and-bootstrap.md#settings). An example file
+  lives at `bot.properties.example`.
+- **Build** — `./mvnw package` produces `target/netneutrality.jar` (Shade fat JAR, main class
+  `me.bobert.netneutrality.App`). Checkstyle (`checkstyle.xml`) runs in the `test` phase
+  and fails the build on violations.
+- **Run** — the preferred method is Docker Compose (`docker compose build && docker compose up -d`),
+  which also provisions the MariaDB database. See `README.md` and `docker-compose.yml`.
+
+## Package map
+
+| Package | Contents |
+|---|---|
+| `me.bobert.netneutrality` | Entry point (`App`) |
+| `…bootstrap` | `ApplicationContext`, `Lifecycle`, `BotState`, `ReflectionHelper` |
+| `…core.command` | Command engine (registry, processor, manager, options, impl bases) |
+| `…core.context` | Context interfaces, abstract bases (`CommandContext`, `TaskContext`, etc.) |
+| `…core.tasks` | Task engine (manager, subtypes, traits, persistence, generic buttons) |
+| `…core.thread` | Executors & scheduling (`ThreadManager`, `ScheduledTaskManager`, `BaseThreadFactory`) |
+| `…core` | `LogHandler`, `NetNeutralityBot` |
+| `…command.*` | Concrete command implementations (`admin`, `basic`, `bot`, `crypto`, `custom`, `git`, `music`, `react`) |
+| `…context.command` / `…context.tasks` | Concrete context implementations (slash, message, button, modal, emoji, etc.) |
+| `…context` | `MusicChannelContext` |
+| `…tasks.*` | Concrete task implementations (`git`, `help`, `music`, `reaction`) |
+| `…db` | Session/migration, `Repository`, `JpaUtils`, `GSettings` |
+| `…db.entities` / `…db.repository` / `…db.service` | Persistence model, repositories, services |
+| `…hooks` | `EventsHandler` |
+| `…http` | Internal web API and HTTP client module |
+| `…music` | Music domain (service, manager, queue, sources, tracks) |
+| `…utils` | `Settings` / `SettingsProvider`, `ChannelMessagePurger`, `MusicUtils` |
+| `…shared.util` | Cross-cutting helpers |
+| `…exceptions` | Custom exception hierarchy |

docs/commands.md

@@ -0,0 +1,169 @@
+# Commands
+
+**Packages:** `me.bobert.netneutrality.framework.command` (framework),
+`me.bobert.netneutrality.feature.*.command` (concrete commands)
+
+A **Command** is what a user executes on Discord. It receives a
+[`CommandContext`](contexts.md#commandcontext) and runs logic based on it. There are two primary
+kinds:
+
+- **Slash commands** — first-class Discord application commands. Their structure (options,
+  subcommands, groups) has rules defined by Discord and must be configured **procedurally** via
+  `CommandOptionsBuilder`.
+- **Message (prefix) commands** — a plain message beginning with the configured prefix
+  (`NETNEUTRALITY_BOT_PREFIX`, default `$`).
+
+A core goal of the framework is that **both kinds are authored the same way**: a command declares its
+metadata and options once, and the framework adapts it to either interaction style. Most of that
+adaptation logic lives in `CommandProcessor`.
+
+## The `Command` contract
+
+`Command` (interface) defines:
+
+- Metadata — `getCommandName()`, `getDescription()`, `getCategory()`
+  ([`CommandCategory`](#commandcategory)).
+- Type — `getType()` (`SLASH` by default).
+- Permissions — `needAdmin()`, `canBeExecutedBy(...)`, guild-only / slash-only constraints.
+- Option declaration — `registerCommandOptions(CommandOptionsBuilder)` (procedural option setup).
+- Execution — `execute(CommandContext) : CommandExecutionResult`.
+
+### Base implementations (`core.command.impl`)
+
+| Class | Adds |
+|---|---|
+| `AbstractCommand` | Default `Command` implementation; type defaults to `SLASH`; basic permission logic. |
+| `AdminCommand` | Sets `needAdmin() = true` and category `ADMINISTRATION`. |
+| `MusicCommand` | Guild-only; verifies the guild's music role and music channel before execution. |
+| `MessageMenuCommand` | Discord **message** context-menu command; skips option registration; wraps the target `Message`. |
+| `UserMenuCommand` | Discord **user** context-menu command; skips option registration; wraps the target `User`. |
+
+## Unified options
+
+To let one command definition serve both slash and message input, values are read through a wrapper
+interface:
+
+- `CommandOption` (interface) — uniform accessors: `getAsString()`, `getAsInt()`, `getAsMember()`,
+  `getAsBoolean()`, … .
+- `SlashCommandOption` — wraps JDA's `OptionMapping` (Discord already parsed the value).
+- `MessageCommandOption` — wraps a value parsed manually from the message text.
+
+### Procedural option configuration — `CommandOptionsBuilder`
+
+`CommandOptionsBuilder` implements JDA's `SlashCommandData` and acts as a proxy over JDA's internal
+`CommandDataImpl`. A command builds its argument surface in `registerCommandOptions(builder)` by
+adding options, subcommands, and subcommand groups. The same declaration is used both to:
+
+1. register the slash command with Discord (see [registration](#registration-lifecycle)), and
+2. drive the message-command parser (which tries to match tokens in the message against the declared
+   `OptionData`).
+
+## Command management
+
+### `CommandManager`
+
+Responsible for **discovery** and **registration**.
+
+- **Discovery** — at `init()`, uses [`ReflectionHelper`](utilities-and-bootstrap.md#reflectionhelper)
+  to scan for `Command` implementations and instantiate them.
+- **Storage** — commands are kept in a `ConcurrentHashMap<String, CommandContainer>` keyed by command
+  name.
+- **Slash registration** — `registerSlashCommands(JDA)` converts each command's declaration into JDA
+  `SlashCommandData` and pushes it to Discord's API.
+
+### `CommandContainer`
+
+Wraps a `Command` instance together with its JDA metadata (`CommandDataImpl`). It also builds the
+"usage" string shown by the help command.
+
+### `CommandCategory`
+
+Enum grouping commands for help/display purposes (e.g. `ADMINISTRATION`, `UTILITY`, `MUSIC`,
+`CRYPTO`, and an unlisted/hidden group for owner/debug commands).
+
+### `CommandExecutionResult`
+
+The value returned by `execute(...)`. It encodes the outcome and any response payload:
+
+- `success(...)` — normal success (optionally with a message/embed to send).
+- `error(...)` / `warning(...)` — failure/advisory outcomes with a message.
+- `none()` — nothing to send synchronously (the command handles its own async response, e.g. music).
+- May also carry a follow-up **`Task`** so a command can install an interactive
+  [task](tasks.md) (e.g. buttons) as part of its result.
+
+## The dispatch flow — `CommandProcessor`
+
+`CommandProcessor` is constructed with the `CommandContext` and driven by `dispatch()`:
+
+1. **Resolution** — match the invoked name against a `CommandContainer` in `CommandManager`.
+2. **Validation**
+   - command enabled?
+   - guild-only / slash-only constraints satisfied?
+   - **permissions** — `canBeExecutedBy(...)` and, for admin commands, `needAdmin()` verified against
+     the bot owner (`NETNEUTRALITY_BOT_OWNER`) and the member's guild-admin status.
+3. **Usage parsing (`checkUsage`)** — detect whether a subcommand or subcommand group is being
+   invoked and record the active subcommand on the context.
+4. **Option parsing**
+   - **Slash** — Discord already parsed the arguments; map each `OptionMapping` to a
+     `SlashCommandOption`.
+   - **Message** — `MessageCommandContext` tokenizes the message and matches tokens against the
+     declared `OptionData` (resolving mentions to members/roles, parsing integers/booleans, etc.).
+5. **Execution** — call `command.execute(context)`.
+6. **Result handling** — act on the returned `CommandExecutionResult`: send success/error/warning
+   responses, or, if a `Task` was returned, register it with the [`TaskManager`](tasks.md).
+
+Errors are surfaced through the exception hierarchy
+([`CommandExecutionException`](utilities-and-bootstrap.md#exceptions), and
+`GracefulContextError` for user-facing, non-logged failures).
+
+## Registration lifecycle
+
+```
+App.startup()
+   ├─ CommandManager.init()               // reflective discovery → ConcurrentHashMap
+   └─ CommandManager.registerSlashCommands(jda)  // push SlashCommandData to Discord
+```
+
+At runtime, an incoming command event becomes a `CommandContext` in the
+[`EventsHandler`](events.md), which calls `new CommandProcessor(context).dispatch()`.
+
+## Command catalog
+
+Concrete commands live under `me.bobert.netneutrality.feature.*.command`, grouped by feature package:
+
+| Command | Package | Type | Description |
+|---|---|---|---|
+| `BlacklistCommand` | `admin` | Slash | Manage the server's word blacklist. |
+| `ReactionCommand` | `admin` | Slash | Manage emoji-reaction roles on the server. |
+| `HelpCommand` | `basic` | Slash | List every command with its usage. |
+| `PingCommand` | `basic` | Slash | Reply with the gateway ping. |
+| `ConfigureCommand` | `bot` | Slash | Configure the bot for the server (subcommands). |
+| `CryptoPriceCommand` | `crypto` | Slash | Fetch cryptocurrency prices. |
+| `ReportIssueCommand` | `git` | Slash | Report a bug (opens the GitLab report flow). |
+| `PlayCommand` | `music` | Slash | Search/queue and start playback. |
+| `QueueCommand` / `ViewQueueCommand` | `music` | Slash | View/manage the queue. |
+| `SkipCommand` / `VoteSkipCommand` | `music` | Slash | Skip (or vote-skip) the current track. |
+| `ClearQueueCommand` / `ShuffleCommand` | `music` | Slash | Clear / shuffle the queue. |
+| `JoinCommand` / `LeaveCommand` | `music` | Slash | Join / leave the voice channel. |
+| `CurrentlyPlayingCommand` | `music` | Slash | Show the currently playing track. |
+| `ResumeCommand` / `StopCommand` / `VolumeCommand` | `music` | Slash | Playback controls. |
+| `BitconnectCommand` | `music` | Slash | Novelty music command. |
+| `CreateEmojiReaction` / `ModifyEmojiReaction` | `react` | Message menu | Create/modify emoji-role mappings from a message. |
+| `DatabaseCommand`, `PurgeCommand`, `ShutdownCommand`, `JoinClanCommand`, `TestCommand`, `SlashCommandTest`, `TrackStuckTest` | `custom` | Mixed | Owner/debug and personal utilities (the `custom` package is gitignored per-deployment). |
+
+### Representative commands
+
+**`PingCommand` (simplest slash command)** — extends `AbstractCommand`, overrides `execute` to return
+`CommandExecutionResult.success(...)` containing the JDA gateway ping. It illustrates the minimal
+execution path (no options, synchronous response).
+
+**`ConfigureCommand` (complex slash command)** — uses `registerCommandOptions` to declare several
+`SubcommandData` (e.g. music-volume, error-logging). In `execute`, it switches on
+`context.getSubcommand()` and reads typed values via `context.getOption(name, resolver)`, then
+persists them through the [guild settings service](persistence.md#service-layer).
+
+**`PlayCommand` (music)** — extends `MusicCommand` (so it enforces guild-only + music role/channel).
+It declares a single required `STRING` query option, delegates loading to
+[`MusicManager`](music.md), and returns `CommandExecutionResult.none()` because the audio subsystem
+produces the user-facing response asynchronously (often installing a
+[`LoadPlaylistTask`](tasks.md#concrete-task-catalog) with choice buttons).

docs/contexts.md

@@ -0,0 +1,154 @@
+# Contexts
+
+**Packages:** `me.bobert.netneutrality.framework.context` (framework),
+`me.bobert.netneutrality.framework.context` (concrete implementations)
+
+A **Context** is a high-level abstraction over a Discord event. It hides the differences between the
+many JDA event types (slash command, message, button, modal, reaction, …) behind a single, uniform
+API for reading who/where the event came from and for replying to it.
+
+Contexts are created either by the [`EventsHandler`](events.md) when Discord triggers an event, or by
+another context further down a flow (for example, a reply produces an [`AsyncContext`](#asynccontext)
+that can be edited later). A context can be handled by one of three flows depending on its type and
+the event it wraps: the [command processor](commands.md), the [task manager](tasks.md), or a simple
+lambda. **The id of a context only matters for tasks** — the task manager uses `getId()` to locate
+the `Task` that should run (see [tasks.md](tasks.md)).
+
+## Type hierarchy
+
+```
+Context (interface)
+├── InteractionContext (interface)   ── reply/defer/ack via IReplyCallback + InteractionHook
+├── NoMessageContext (interface)     ── defaults for events without a triggering message
+│   └── MessageContext (interface)   ── adds a triggering Message (prefix commands, replies)
+│
+└── AbstractContext (abstract, implements Context)   ── stores JDA/Guild/Channel/Member/User
+    ├── CommandContext (abstract)    ── command flow; holds CommandOptions + subcommand metadata
+    │   ├── SlashCommandContext
+    │   ├── MessageCommandContext
+    │   ├── MessageMenuContext
+    │   └── UserMenuContext
+    ├── TaskContext (abstract)       ── task flow; abstract getId(); contextData state map
+    │   ├── ButtonTaskContext
+    │   ├── EmojiTaskContext
+    │   ├── MessageTaskContext
+    │   └── ModalTaskContext
+    ├── AsyncContext                 ── wraps the result of a previous reply (edit/follow-up)
+    └── MusicChannelContext          ── synthetic context targeting a guild's music channel
+```
+
+## Core framework types
+
+### `Context` (interface)
+
+The root contract for every context. Notable methods:
+
+- `getJDA()`, `getGuild()`, `getChannel()`, `getGuildUser()` (`Member`), `getDiscordUser()` (`User`)
+- `reply(...)` — unified send; overloads support plain text, embeds, message components, an
+  `ephemeral` flag, and an async callback that receives an [`AsyncContext`](#asynccontext) for
+  follow-up edits.
+- `defer(ephemeral, consumer)` — signals "thinking…" and later completes the response.
+- `ack(ephemeral)` — minimal acknowledgement of the event.
+- `getInteractionHook()` — the JDA `InteractionHook` when the underlying event is an interaction.
+
+### `AbstractContext` (abstract class)
+
+Base implementation that stores the common JDA entities (`JDA`, `Guild`, `MessageChannel`, `Member`,
+`User`) and exposes them via the `Context` getters. Its constructor also sets the **Sentry user**
+(id + effective name) so any error captured while handling this context is attributed to the right
+Discord user:
+
+```java
+if (user != null) {
+    io.sentry.protocol.User sentryUser = new io.sentry.protocol.User();
+    sentryUser.setId(user.getId());
+    sentryUser.setUsername(user.getEffectiveName());
+    Sentry.setUser(sentryUser);
+}
+```
+
+### `InteractionContext` (interface)
+
+Behavioral mix-in for events that are JDA `Interaction`s (slash commands, buttons, modals, context
+menus). It implements `reply`/`defer`/`ack` in terms of `IReplyCallback` and `InteractionHook`, so
+these contexts can reply ephemerally, defer, and edit the original response.
+
+### `NoMessageContext` / `MessageContext` (interfaces)
+
+- `NoMessageContext` — provides sensible defaults for events that have **no** triggering message
+  (e.g. reactions, interactions).
+- `MessageContext extends NoMessageContext` — adds access to a triggering `Message`, used by prefix
+  commands and by replies that drive step tasks.
+
+## Command contexts
+
+### `CommandContext`
+
+Abstract base for the [command flow](commands.md). It carries the parsed
+[`CommandOption`s](commands.md#unified-options) and the active subcommand / subcommand-group metadata,
+and exposes type-safe option access, e.g. `getOption(name, resolver)`. Concrete subclasses adapt a
+specific JDA event to this API.
+
+| Class                   | Wraps                            | Notes                                                                                                                                            |
+|-------------------------|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| `SlashCommandContext`   | `SlashCommandInteractionEvent`   | Options already parsed by Discord; maps `OptionMapping` → `SlashCommandOption`. Interaction-based replies.                                       |
+| `MessageCommandContext` | `MessageReceivedEvent` (prefix)  | Contains the **manual parser** that turns the raw message string into `CommandOption`s (mentions, integers, booleans, …). Message-based replies. |
+| `MessageMenuContext`    | `MessageContextInteractionEvent` | "Apps → …" action on a message; exposes the target `Message`.                                                                                    |
+| `UserMenuContext`       | `UserContextInteractionEvent`    | "Apps → …" action on a user; exposes the target `User`.                                                                                          |
+
+## Task contexts
+
+### `TaskContext`
+
+Abstract base for the [task flow](tasks.md). Two things distinguish it:
+
+- **`getId()` (abstract)** — the id used by `TaskManager` to find the matching `Task`. How the id is
+  derived depends on the concrete subtype (see the table below and [tasks.md](tasks.md#the-task-id)).
+- **`contextData` map** — a small state bag used to carry values between steps of a multi-step flow.
+
+| Class                | Wraps                              | `getId()` derived from                                     |
+|----------------------|------------------------------------|------------------------------------------------------------|
+| `ButtonTaskContext`  | `ButtonInteractionEvent`           | `getComponentId()` of the clicked button                   |
+| `ModalTaskContext`   | `ModalInteractionEvent`            | modal `customId`                                           |
+| `EmojiTaskContext`   | `MessageReactionAddEvent`          | composite `guildId:messageId`                              |
+| `MessageTaskContext` | `MessageReceivedEvent` (no prefix) | the id of the message being replied to (drives step tasks) |
+
+## Reply mechanism & `AsyncContext`
+
+### `AsyncContext`
+
+`me.bobert.netneutrality.framework.context.AsyncContext` wraps the **result** of a previous reply — either an
+`InteractionHook` (for interactions) or a `Message` (for message replies) — so follow-up actions are
+expressed the same way regardless of the original trigger:
+
+```java
+context.reply("Initial response", async -> {
+    // 'async' is an AsyncContext for the message just sent
+    async.edit("Updated response");
+});
+```
+
+Under the hood:
+
+- **Interactions** — edits/follow-ups go through `hook.editOriginal()` / `hook.sendMessage()`.
+- **Messages** — edits/follow-ups go through `message.editMessage()` / `message.reply()`.
+
+This is what makes the command and task code path-agnostic: authors write against `Context` /
+`AsyncContext` and never branch on "was this a slash command or a text message?".
+
+### `MusicChannelContext`
+
+A synthetic `AbstractContext` that targets a guild's configured **music channel** rather than the
+channel an event came from. The music subsystem uses it to post now-playing / queue messages into the
+correct channel even when playback state changes without a fresh user interaction. See
+[music.md](music.md).
+
+## End-to-end summary
+
+| Event                           | Context                 | Flow    | Async result wraps |
+|---------------------------------|-------------------------|---------|--------------------|
+| `SlashCommandInteractionEvent`  | `SlashCommandContext`   | Command | `InteractionHook`  |
+| `MessageReceivedEvent` (prefix) | `MessageCommandContext` | Command | `Message`          |
+| `ButtonInteractionEvent`        | `ButtonTaskContext`     | Task    | `InteractionHook`  |
+| `MessageReactionAddEvent`       | `EmojiTaskContext`      | Task    | `Message`          |
+| `ModalInteractionEvent`         | `ModalTaskContext`      | Task    | `InteractionHook`  |

docs/events.md

@@ -0,0 +1,102 @@
+# Event Handling & Routing
+
+**Package:** `me.bobert.netneutrality.platform.event`
+**Primary class:** `EventsHandler`
+
+`EventsHandler` is the single JDA `EventListener` registered on the `JDA` instance
+(`jda.addEventListener(new EventsHandler())` in `App.startup()`). It is the funnel through
+which **every** gateway event passes. Its job is to translate a raw JDA event into a
+[Context](contexts.md) and route that context to the correct subsystem.
+
+## Listener registry
+
+Listeners are held in a static, thread-safe map keyed by the JDA event class:
+
+```java
+private static final Map<Class<? extends Event>, Function<? extends Event, Context>> listeners
+        = new ConcurrentHashMap<>();
+```
+
+Each entry is a **factory function**: given an event of that type, it returns a `Context` (or `null`).
+The map is populated once in a `static {}` block.
+
+### `addListener` vs `addGenericListener`
+
+- `addListener(Class<T>, Function<? super T, Context>)` — registers a factory that produces a
+  `Context` to be routed onward (command or task flow).
+- `addGenericListener(Class<T>, Consumer<T>)` — registers a factory that runs a side-effecting
+  consumer and returns `null`, so nothing is routed onward. This is the **lambda flow** for simple
+  events.
+
+## Registered events
+
+| JDA event | Produces | Flow |
+|---|---|---|
+| `MessageReceivedEvent` (prefix match) | `MessageCommandContext` | Command |
+| `MessageReceivedEvent` (no prefix) | `MessageTaskContext` | Task |
+| `SlashCommandInteractionEvent` | `SlashCommandContext` | Command |
+| `UserContextInteractionEvent` | `UserMenuContext` | Command |
+| `MessageContextInteractionEvent` | `MessageMenuContext` | Command |
+| `ButtonInteractionEvent` | `ButtonTaskContext` | Task |
+| `ModalInteractionEvent` | `ModalTaskContext` | Task |
+| `MessageReactionAddEvent` | `EmojiTaskContext` | Task |
+| `GuildJoinEvent` | — (consumer) | Lambda |
+| `GuildLeaveEvent` | — (consumer) | Lambda |
+
+### Message routing detail
+
+For `MessageReceivedEvent` the factory:
+
+1. Ignores messages authored by bots and webhook messages (returns `null`).
+2. Reads the configured prefix (`NETNEUTRALITY_BOT_PREFIX`, default `$`).
+3. If the trimmed message starts with the prefix → **`MessageCommandContext`** (command flow).
+4. Otherwise → **`MessageTaskContext`** (task flow). This lets ordinary messages participate in the
+   task system, e.g. as a reply that advances a [step task](tasks.md#33-step-tasks).
+
+### Guild lifecycle (lambda flow)
+
+- `GuildJoinEvent` — resolves `GuildService.get(guild)`; if debug logging is enabled for that guild,
+  sends a notice to the debug channel.
+- `GuildLeaveEvent` — `GuildService.get(guild).deleteGuild()` removes the guild's stored data.
+
+## Dispatch algorithm
+
+```java
+@Override
+public void onEvent(@Nonnull GenericEvent event) {
+    handleEvent((Event) event);
+}
+
+private void handleEvent(Event event) {
+    Class<?> eventClass = event.getClass();
+    while (eventClass != null) {
+        if (listeners.containsKey(eventClass)) {
+            Context context = listeners.get(eventClass).apply(event);
+            if (context instanceof CommandContext c) handleCommand(c);
+            if (context instanceof TaskContext t)    handleTask(t);
+            break;
+        }
+        eventClass = eventClass.getSuperclass();   // walk up the class hierarchy
+    }
+}
+```
+
+Key points:
+
+- **Superclass walk** — if the exact event class is not registered, the handler walks up the
+  superclass chain until it finds a match. This means a listener registered for a base event type
+  also catches subclasses.
+- **Routing by context type** — the resulting object is routed purely by its runtime type:
+  a `CommandContext` goes to `CommandProcessor.dispatch()`, a `TaskContext` goes to
+  `TaskManager.getInstance().handle(context)`.
+- **`null` contexts** (bot messages, consumer-only events) are simply not routed anywhere.
+
+## Extending the event system
+
+To handle a new event type:
+
+1. Add an `addListener(SomeEvent.class, SomeContext::new)` (or `addGenericListener(...)` for a
+   consumer-only side effect) to the `static {}` block.
+2. If it should run the command or task flow, make the produced context extend
+   [`CommandContext`](contexts.md#commandcontext) or [`TaskContext`](contexts.md#taskcontext)
+   respectively.

docs/music.md

@@ -0,0 +1,93 @@
+# Music
+
+**Package:** `me.bobert.netneutrality.feature.music`
+**Engine:** [Lavaplayer](https://github.com/lavalink-devs/lavaplayer) 2.2.6 + the Lavalink YouTube
+source 1.18.2.
+
+The music subsystem provides per-guild audio playback: searching/loading tracks from multiple
+sources, queueing, scheduling, and streaming audio into a Discord voice channel.
+
+## Key classes
+
+| Class | Responsibility |
+|---|---|
+| `MusicManager` | Central per-guild coordinator; owns the `AudioPlayer` and `TrackScheduler`. |
+| `QueueManager` | Holds the guild's track queue (`LinkedBlockingDeque<TrackInfo>`); enqueue/skip/shuffle. |
+| `TrackScheduler` | `AudioEventAdapter`; reacts to Lavaplayer events (`onTrackEnd`, `onTrackStuck`). |
+| `TrackLoadingHandler` | `AudioLoadResultHandler`; handles track/playlist/no-match/failure results. |
+| `TrackInfo` | Value object pairing an `AudioTrack` with its requester (`Member`). |
+| `SourceFinder` | Identifies the source/type of a query (YouTube, Udio, HTTP, …). |
+| `AudioPlayerSendHandler` | Bridges Lavaplayer output to JDA's `AudioSendHandler`. |
+| `source/UdioAudioSourceManager` | Custom Lavaplayer source manager for udio.com. |
+| `source/UdioAudioTrack` | Udio track; delegates playback to `Mp3AudioTrack`. |
+
+`MusicManager` keeps a static `Map<String, MusicManager>` of managers keyed by guild id, so each guild
+has its own player, scheduler, and queue.
+
+## Startup
+
+`MusicManager.initPlayerManager()` (called from
+[`App.startup()`](architecture.md#startup-lifecycle)) creates the Lavaplayer
+`AudioPlayerManager` and registers the source managers (YouTube, SoundCloud, the custom
+[Udio source](#custom-udio-source), and HTTP).
+
+## Audio pipeline (end-to-end)
+
+```
+/play query
+   │
+   ▼
+MusicManager.play(query, ctx)
+   │  SourceFinder identifies the source
+   ▼
+audioPlayerManager.loadItemOrdered(guild, identifier, new TrackLoadingHandler(...))
+   │
+   ├─ trackLoaded ──▶ connect to voice (MusicUtils) ──▶ QueueManager.queue(track, member)
+   ├─ playlistLoaded / searchResults ──▶ install a LoadPlaylistTask (choice buttons)
+   ├─ noMatches ──▶ reply "nothing found"
+   └─ loadFailed ──▶ reply / log error
+   │
+   ▼
+QueueManager: if the player is idle, start immediately; else append to the deque
+   │
+   ▼
+AudioPlayerSendHandler streams PCM/Opus frames to the voice channel
+   │
+   ▼ (track ends)
+TrackScheduler.onTrackEnd ──▶ QueueManager.startNextTrack()
+```
+
+- **Requester tracking** — each queued item is a `TrackInfo` (track + requesting `Member`), used for
+  now-playing/queue displays and vote-skip.
+- **Playlists / search** — playlist and multi-result loads produce a
+  [`LoadPlaylistTask`](tasks.md#concrete-task-catalog) with per-result buttons
+  (`LoadTrackFromPlaylistTask`), tying the music and [task](tasks.md) subsystems together. Playlist
+  size is bounded by the [`MUSIC_MAXPLAYLISTSIZE`](persistence.md#gsettings) guild setting.
+- **Stuck tracks** — `TrackScheduler.onTrackStuck` attempts recovery (reload/skip).
+- **Output** — playback messages are posted through a
+  [`MusicChannelContext`](contexts.md#musicchannelcontext) so they land in the guild's configured
+  music channel.
+
+## Custom Udio source
+
+`UdioAudioSourceManager` scrapes udio.com track pages: it extracts track metadata (title, artist,
+duration) and a direct playback URL from the Next.js payload (`self.__next_f.push(...)` calls) in the
+page HTML. Because Udio playback URLs expire, `UdioAudioTrack` **re-fetches** the URL during the
+`process` phase of the pipeline before streaming, delegating the actual decode/playback to Lavaplayer's
+`Mp3AudioTrack`.
+
+## Guild lifecycle & cleanup
+
+- `MusicPlayerAutoDisconnect` (scheduled task) leaves voice when the player has been idle.
+- `MusicManagerCleanup` (scheduled task) evicts unused per-guild `MusicManager` instances from the
+  static map.
+- On shutdown, `MusicManager.disconnectPlayers()` stops all players and disconnects from voice
+  (called from [`App.shutdown()`](architecture.md#shutdown-lifecycle)).
+
+## Related commands
+
+All music commands extend [`MusicCommand`](commands.md#base-implementations-corecommandimpl) (guild
+only + music role/channel enforced): `PlayCommand`, `SkipCommand`/`VoteSkipCommand`,
+`QueueCommand`/`ViewQueueCommand`, `ClearQueueCommand`, `ShuffleCommand`, `JoinCommand`/`LeaveCommand`,
+`CurrentlyPlayingCommand`, `ResumeCommand`/`StopCommand`, `VolumeCommand`, `BitconnectCommand`. See
+[commands.md](commands.md#command-catalog).

docs/persistence.md

@@ -0,0 +1,128 @@
+# Persistence & Database
+
+**Packages:** `me.bobert.netneutrality.platform.persistence` (session/migration),
+`me.bobert.netneutrality.db` (entities, repositories, services).
+**Resources:** `hibernate.cfg.xml`, `db/migration/V1__initial_schema.sql`.
+
+## Stack
+
+| Concern    | Technology                                                                    |
+|------------|-------------------------------------------------------------------------------|
+| ORM        | Hibernate 7.1.9 (Jakarta JPA)                                                 |
+| Engine     | MariaDB 11 (per `docker-compose.yml`), MySQL Connector/J 9.7.0 driver, InnoDB |
+| Pooling    | HikariCP (via `hibernate-hikaricp`)                                           |
+| Migrations | Flyway 11.20.3 (`flyway-core` + `flyway-mysql`)                               |
+
+Configuration is externalized via `Settings` (env vars / `bot.properties`):
+`MYSQL_HOST`, `MYSQL_PORT`, `MYSQL_USER`, `MYSQL_PASSWORD`, `MYSQL_DATABASE`.
+
+## Session & migration lifecycle
+
+Both are wired in at [startup](architecture.md#startup-lifecycle):
+
+1. **`SessionManager.getSessionFactory()`** — lazily builds the Hibernate `SessionFactory`. It reads
+   the static config from `hibernate.cfg.xml` (dialect `MySQLDialect`, driver
+   `com.mysql.cj.jdbc.Driver`, the Hikari connection provider, and the mapped entity list) and
+   overrides the JDBC url/user/password from environment variables:
+
+   ```java
+   settings.put(Environment.JAKARTA_JDBC_URL,
+       String.format("jdbc:mysql://%s:%s/%s", dbHost, dbPort, dbName));
+   settings.put(Environment.JAKARTA_JDBC_USER, dbUser);
+   settings.put(Environment.JAKARTA_JDBC_PASSWORD, dbPass);
+   ```
+
+2. **`DatabaseMigration.migrate()`** — runs `flyway.migrate()` against the same database, applying the
+   versioned scripts under `src/main/resources/db/migration/` (starting with
+   `V1__initial_schema.sql`). The Flyway Maven plugin (`flyway-dev.sh`/`.ps1`) is available for local
+   development, using `FLYWAY_URL` / `FLYWAY_USER` / `FLYWAY_PASSWORD`.
+
+3. **`SessionManager.shutdown()`** — destroys the service registry / releases the pool on shutdown.
+
+Repositories obtain sessions through the factory; transactional access uses helpers in
+[`JpaUtils`](utilities-and-bootstrap.md) (open session, run in a transaction, close).
+
+## Entity catalog
+
+Entities live in `me.bobert.netneutrality.data.entity` and are prefixed with `O`. `OGuild` is the hub
+of a star-shaped model; most other tables reference `guild_id` with `ON DELETE CASCADE`.
+
+| Entity          | Table            | Key                      | Relationships / notes                                                                                  |
+|-----------------|------------------|--------------------------|--------------------------------------------------------------------------------------------------------|
+| `OGuild`        | `guilds`         | `guild_id` (String)      | Central entity; one-to-many with settings, blacklist, log messages, logging.                           |
+| `OGuildSetting` | `guild_settings` | `id` (auto int)          | Many-to-one `OGuild`; key/value guild settings.                                                        |
+| `OBlacklist`    | `blacklist`      | `id` (auto int)          | Many-to-one `OGuild`; blacklisted words.                                                               |
+| `OLogging`      | `logging`        | `OLoggingId` (composite) | Composite key `guild_id` + `channel_id`; `@MapsId` to `OGuild`; debug/error log channel config.        |
+| `OLoggingId`    | — (embeddable)   | —                        | `@Embeddable`/`@IdClass` for the composite key.                                                        |
+| `OLogMessage`   | `log_message`    | `id` (auto int)          | Many-to-one `OGuild`; message logging history.                                                         |
+| `OTask`         | `tasks`          | `id` (auto int)          | [Persistable task](tasks.md#31-persistable-tasks) state; unique `task_id`, class name, JSON `payload`. |
+| `OWebUser`      | `web_users`      | `id` (String)            | Web dashboard user (tokens/expiry). *Present in schema & code but not listed in `hibernate.cfg.xml`.*  |
+
+### ER overview
+
+```
+                    ┌───────────────┐
+                    │    OGuild     │  (guilds.guild_id)
+                    └───────┬───────┘
+        ┌───────────┬───────┼────────────┬─────────────┐
+        ▼           ▼       ▼            ▼             ▼
+ OGuildSetting  OBlacklist  OLogging   OLogMessage   (…)
+ guild_settings  blacklist  logging    log_message
+   (FK guild)    (FK guild) (PK guild+ (FK guild)
+                             channel)
+
+  OTask (tasks)          OWebUser (web_users)     ── standalone
+```
+
+`OTask` and `OWebUser` are not tied to the guild graph.
+
+## Repository layer
+
+A lightweight generic repository pattern is used.
+
+- **`Repository<O>`** (interface) — generic CRUD: `findAll()`, `findById(String)`, `save(O)` (via
+  `session.merge()`), `deleteBy(String)`.
+- **`BlacklistRepository`** — find-by-guild and case-insensitive word lookups.
+- **`GuildRepository`** — CRUD for guilds.
+- **`GuildSettingRepository`** — set/get setting values; removes rows that equal the default value.
+- **`MessageRepository`** — message logging / edit history.
+- **`TaskRepository`** — CRUD for `OTask` rows (used by the task persistence flow).
+
+## Service layer
+
+Services wrap repositories with business logic and **caching**.
+
+- **`GuildService`** — gateway for guild operations; caches one `GuildService` per guild id
+  (`ConcurrentHashMap`); `findOrCreate` guarantees a guild row exists; `deleteGuild()` on leave;
+  `isDebugEnabled()` / debug-channel helpers used by [`EventsHandler`](events.md) and
+  [`LogHandler`](utilities-and-bootstrap.md#loghandler).
+- **`BlacklistService`** — maintains a `blacklistCache` (guild id → set of words) for fast message
+  filtering.
+- **`GuildSettingService`** — reads/writes guild settings backed by [`GSettings`](#gsettings); caches
+  values in `settingsCache` and reloads on change; used by the
+  [web API settings endpoints](web-api.md).
+- **`TaskService`** — serializes [`PersistableTask`](tasks.md#31-persistable-tasks) instances to JSON
+  for the `tasks` table and reconstructs them at startup via
+  [`TaskRegistry`/`TaskFactory`](tasks.md#31-persistable-tasks).
+
+## GSettings
+
+`GSettings` is an **enum** of the available per-guild configuration keys and their defaults:
+
+| Setting                 | Default |
+|-------------------------|---------|
+| `MUSIC_ROLE`            | (none)  |
+| `MUSIC_CHANNEL`         | (none)  |
+| `MUSIC_VOLUME`          | `30`    |
+| `MUSIC_MAXPLAYLISTSIZE` | `20`    |
+
+`GuildSettingService` looks up an `OGuildSetting` row by the enum `name()`; if no row exists for a
+guild/setting, the enum's `defaultValue` is used. This is how `MusicCommand` obtains the guild's music
+role/channel and how `ConfigureCommand` persists changes.
+
+## Schema (`V1__initial_schema.sql`)
+
+The initial migration creates the tables backing the entities above (`guilds`, `guild_settings`,
+`blacklist`, `logging`, `log_message`, `tasks`, `web_users`), with `guild_id` foreign keys and
+`ON DELETE CASCADE` from the guild-scoped tables to `guilds`. Subsequent schema changes should be
+added as new `V2__…`, `V3__…` Flyway scripts in the same directory.

docs/tasks.md

@@ -0,0 +1,315 @@
+# Tasks
+
+**Packages:** `me.bobert.netneutrality.framework.task` (framework),
+`me.bobert.netneutrality.feature.*.task` (concrete tasks)
+
+Tasks are one of the more advanced concepts in the bot. A **Task** is a unit of logic that is looked
+up and executed by **id** when a matching Discord event arrives, as opposed to a
+[command](commands.md) which is looked up by name.
+
+The original motivation was **Discord interactions** (buttons). When a user clicks a button, Discord
+sends a `ButtonInteractionEvent` whose id is `getComponentId()`. A `Task` with that same id was
+inserted earlier (typically by the command that created the button), so the `TaskManager` can find
+the task and execute it. The system has since grown to cover several task subtypes:
+
+| Subtype                                      | Trigger                            | Id source                              |
+|----------------------------------------------|------------------------------------|----------------------------------------|
+| [Button task](#button-emoji-and-modal-tasks) | `ButtonInteractionEvent`           | button `componentId`                   |
+| [Modal task](#button-emoji-and-modal-tasks)  | `ModalInteractionEvent`            | modal `customId`                       |
+| [Emoji task](#button-emoji-and-modal-tasks)  | `MessageReactionAddEvent`          | composite `guildId:messageId`          |
+| [Step task](#33-step-tasks)                  | replied-to message                 | last-message id (assigned dynamically) |
+| [Built-in task](#32-built-in-tasks)          | button with a hardcoded id         | hardcoded id                           |
+| [Persistable task](#31-persistable-tasks)    | any of the above, restored from DB | as stored                              |
+| [Scheduled task](#34-scheduled-tasks)        | timer                              | n/a (time-based, not id-based)         |
+
+## The `Task` id
+
+The id is the **primary lookup key** used by `TaskManager`. How it is derived depends on the subtype:
+
+- **Buttons** → the button's `componentId`.
+- **Modals** → the modal's `customId`.
+- **Emoji reactions** → a composite `guildId:messageId` (a reaction is tied to a specific message).
+- **Step tasks** → start life with a random UUID, then re-key themselves to the DM/last-message id
+  once that message exists (see [step tasks](#33-step-tasks)).
+
+## `Task` contract & lifecycle
+
+`Task` (interface) defines `execute(TaskContext)` and returns a **`Lifecycle`** value that tells the
+`TaskManager` what to do with the task afterwards:
+
+| Lifecycle                  | Meaning                                                           |
+|----------------------------|-------------------------------------------------------------------|
+| `BUILTIN`                  | Task is static and stays registered indefinitely.                 |
+| `KEEP`                     | Keep the task in memory after execution (can run again).          |
+| `REMOVE_SELF`              | Remove this task after execution (one-shot).                      |
+| `REMOVE_SELF_AND_CHILDREN` | Remove this task and all of its [child tasks](#trait-interfaces). |
+
+### Task base classes (`core.tasks.impl`)
+
+```
+AbstractTask (implements Task)
+├── ButtonTask                 ── executed from a ButtonTaskContext
+├── EmojiTask                  ── executed from an EmojiTaskContext
+├── ModalTask                  ── executed from a ModalTaskContext
+├── GenericCustomIdTask        ── task keyed by an explicit custom id
+├── GenericRandomIdTask        ── task keyed by a generated random id
+├── AbstractBuiltInTask        ── base for hardcoded, reflectively-loaded tasks
+├── AbstractPersistableTask    ── base for DB-backed tasks (implements PersistableTask)
+└── AbstractStepTask           ── base for multi-step Q&A flows (implements StepTask)
+```
+
+## `TaskManager`
+
+`me.bobert.netneutrality.framework.task.TaskManager` is the registry, lookup, and execution
+coordinator.
+
+### Registration — `insert`
+
+- Adds the task to the active map keyed by its id.
+- If the task is a [`PersistableTask`](#31-persistable-tasks), it is also **saved to the database**
+  via [`TaskService`](persistence.md#service-layer).
+- If the task is a [`StepTask`](#33-step-tasks) without a message id yet, it is held in a separate
+  `pendingTasks` collection until its id is assigned.
+
+### Execution — `handle(TaskContext)`
+
+1. Look up the task by `context.getId()`.
+2. For ordinary (non-built-in, non-persistable) tasks, acquire a **`ReentrantLock`** so the same task
+   cannot be executed concurrently (prevents double-clicks / races). Tasks that share a
+   [parent](#trait-interfaces) share the same lock id.
+3. Call `task.execute(context)`.
+4. Apply the returned `Lifecycle` (keep / remove / remove-with-children); persistable tasks removed
+   here are also deleted from the DB.
+5. If the task is [`Deletable`](#trait-interfaces), delete the original message/interaction.
+6. Unless the task is [`NotAcknowledgeable`](#trait-interfaces), acknowledge the interaction.
+
+### Startup — `init`
+
+Called from `App.startup()`:
+
+1. Reflectively load all [`BuiltInTask`](#32-built-in-tasks) implementations.
+2. Reflectively load all [`ScheduledTask`](#34-scheduled-tasks) implementations and register them
+   with [`ScheduledTaskManager`](threading.md).
+3. Load persistable tasks from the database (via `TaskService`) and reconstruct them (see
+   [persistence rules](#31-persistable-tasks)).
+
+## Button, emoji and modal tasks
+
+These are the "interaction" tasks and the original purpose of the subsystem:
+
+- **`ButtonTask`** — executed when a button whose `componentId` matches the task id is clicked. The
+  matching context is a [`ButtonTaskContext`](contexts.md#task-contexts).
+- **`ModalTask`** — executed when a modal is submitted; matched by the modal `customId`. A modal is
+  typically opened by another interaction (e.g. `ReportIssueTask` opens a title/description modal).
+- **`EmojiTask`** — executed when a reaction is added to a specific message; matched by the composite
+  `guildId:messageId` id.
+
+The generic helpers `GenericCustomIdTask` / `GenericRandomIdTask` let a command install an ad-hoc,
+function-backed task under a chosen or generated id (e.g. the generic `AcceptButton` / `CancelButton`
+under `tasks/generic`).
+
+## 3.1 Persistable tasks
+
+**Classes:** `PersistableTask` (interface), `AbstractPersistableTask`,
+`core.tasks.persistence.TaskRegistry`, `core.tasks.persistence.TaskFactory`;
+resource `src/main/resources/persistable-tasks.json`; entity
+[`OTask`](persistence.md#entity-catalog).
+
+Persistable tasks survive restarts: they are serialized to the database and rebuilt on startup. The
+rules for *how* a persistable task can be defined and reconstructed live in `TaskRegistry` and
+`TaskFactory`.
+
+### The mapping file — `persistable-tasks.json`
+
+The file declares, for each persistable task class, the constructor parameters and their types:
+
+```json
+{
+  "tasks": [
+    {
+      "class": "me.bobert.netneutrality.feature.reaction.task.EmojiReactionRoleTask",
+      "params": ["guildId", "channelId", "messageId", "emojiMapping"],
+      "types":  ["string",  "string",    "string",    "map"]
+    }
+  ]
+}
+```
+
+Schema:
+
+| Key      | Meaning                                                          |
+|----------|------------------------------------------------------------------|
+| `tasks`  | array of task mappings                                           |
+| `class`  | fully-qualified class name; **must** implement `PersistableTask` |
+| `params` | ordered list of payload field names                              |
+| `types`  | parallel list of types for those fields                          |
+
+Supported types (`TaskFactory.ParamType`): `string` → `String`, `int` → `Integer`, `map` → `Map`.
+
+### `TaskRegistry` — loading the mappings
+
+`TaskRegistry.loadTaskConfig()` reads `persistable-tasks.json` from the classpath and, for each entry,
+registers a `TaskCreator` (a functional interface `PersistableTask fromPayload(JSONObject payload)`)
+keyed by class name:
+
+```java
+taskCreators.put(className, payload -> {
+    try {
+        return TaskFactory.createTaskInstance(className, params, types, payload);
+    } catch (Exception e) {
+        logger.error("Failed to create instance of '{}': {}", className, e.getMessage());
+        return null;
+    }
+});
+```
+
+Entries missing `class`, `params`, or `types` are logged and skipped. Consumers later look up a
+creator via `TaskRegistry.getTaskCreator(className)`.
+
+### `TaskFactory` — reconstructing an instance
+
+`TaskFactory.createTaskInstance(className, params, types, payload)`:
+
+1. Validates that `params.length == types.length`.
+2. Loads the class and verifies it implements `PersistableTask`.
+3. For each declared parameter, converts the JSON `types[i]` to a `ParamType`, then extracts
+   `payload[params[i]]` as the corresponding Java type:
+   - `string` → `payload.getString(name)`
+   - `int` → `payload.getInt(name)`
+   - `map` → `payload.getJSONObject(name).toMap()`
+4. Reflectively resolves the constructor whose parameter types match `types` and instantiates it with
+   the extracted values.
+
+```java
+return (PersistableTask) clazz.getConstructor(classTypes).newInstance(classParams);
+```
+
+> **Rule of thumb for adding a persistable task:** create a class that implements `PersistableTask`
+> (usually by extending `AbstractPersistableTask`), give it a constructor whose parameters match the
+> `params`/`types` you declare, ensure it serializes those same fields into its JSON payload, and add
+> a matching entry to `persistable-tasks.json`. The payload is stored in the
+> [`OTask.payload`](persistence.md#entity-catalog) column and reconstructed via the flow above on
+> startup.
+
+### Persistence round-trip
+
+```
+insert(task)  ──▶ TaskService serializes payload ──▶ OTask row (task_id, class, payload JSON)
+   startup    ──▶ TaskService reads OTask rows ──▶ TaskRegistry.getTaskCreator(class)
+                                                     .fromPayload(payload) ──▶ TaskFactory ──▶ instance
+```
+
+## 3.2 Built-in tasks
+
+**Classes:** `BuiltInTask`, `AbstractBuiltInTask`.
+
+Built-in tasks are hardcoded tasks with hardcoded ids, conceptually similar to commands. They are
+loaded reflectively at startup (in `TaskManager.init()`) and stay registered for the lifetime of the
+bot (`Lifecycle.BUILTIN`).
+
+A button that triggers a built-in task is created from its class:
+
+```java
+Button button = BuiltInTask.createButton(SomeBuiltInTask.class);
+```
+
+This produces a JDA `Button` whose component id equals the built-in task's hardcoded id, so clicking
+it routes straight to that task. Examples: the help buttons `BotInfo`, `CommandHelp`, `ReportBug`
+(`tasks/help`).
+
+## 3.3 Step tasks
+
+**Classes:** `StepTask` (interface), `AbstractStepTask`.
+
+Step tasks ask the user a series of questions and run logic based on each answer. Because Discord has
+no native "conversation" primitive, the abstraction tracks the **last message id** and only runs the
+next step when *that* message is replied to.
+
+Flow:
+
+1. A step task is created (e.g. by a setup command) and sends a prompt message; initially it is keyed
+   by a random UUID and held in `pendingTasks`.
+2. Once the prompt message exists, the task **re-keys itself to that message's id** and moves into the
+   active `tasks` map.
+3. When the user replies to that message, the incoming `MessageReceivedEvent` becomes a
+   [`MessageTaskContext`](contexts.md#task-contexts) whose id is the replied-to message id — so
+   `TaskManager` finds the step task.
+4. `executeStep` validates/processes the answer and returns a `StepResult`:
+   success, failure, or **next step** (which installs the following step task).
+
+`AbstractStepTask` provides answer validation keyed to a step "type" (e.g. a role id, an emoji, …).
+
+## 3.4 Scheduled tasks
+
+**Classes:** `ScheduledTask`, coordinated by
+[`ScheduledTaskManager`](threading.md#scheduledtaskmanager).
+
+Scheduled tasks are time-based background jobs (as opposed to id-based interaction tasks). They are
+loaded reflectively at startup and registered with `ScheduledTaskManager`, which schedules them at a
+fixed interval derived from the task's `TimeFrame` (e.g. minutely / hourly / daily / custom) and
+cancels them all on shutdown.
+
+> **Status:** the scheduled-task abstraction is intended to eventually replace the ad-hoc
+> [`ThreadManager`](threading.md) threads and is still evolving. The concrete scheduled tasks that
+> exist today are listed in the [catalog](#concrete-task-catalog).
+
+## Trait interfaces
+
+Tasks can opt into extra behavior by implementing marker/behavior interfaces in
+`core.tasks.trait`:
+
+| Trait                | Effect                                                                                   |
+|----------------------|------------------------------------------------------------------------------------------|
+| `Deletable`          | After successful execution, `TaskManager` deletes the original message/interaction.      |
+| `NotAcknowledgeable` | Suppresses the default acknowledgement (the task sends its own response).                |
+| `WithButton`         | The task can render itself as a JDA `Button` (`createButton()`).                         |
+| `WithChildren`       | The task tracks child tasks and can clean them up together (`REMOVE_SELF_AND_CHILDREN`). |
+| `WithParent`         | Links a child task to a parent; children share the parent's execution lock.              |
+
+## Concrete task catalog
+
+| Task                        | Package     | Base type                    | Description                                                  |
+|-----------------------------|-------------|------------------------------|--------------------------------------------------------------|
+| `EmojiReactionRoleTask`     | `emoji`     | `EmojiTask` (persistable)    | Assign/remove a role when a user reacts with a mapped emoji. |
+| `AcceptButton`              | `generic`   | `ButtonTask`                 | Generic "accept" button running a supplied function.         |
+| `CancelButton`              | `generic`   | `ButtonTask`                 | Generic "cancel" button running a supplied function.         |
+| `ReportIssueTask`           | `git`       | `ModalTask`                  | Modal to report a bug; creates a GitLab issue.               |
+| `BotInfo`                   | `help`      | `AbstractBuiltInTask`        | Show bot info + invite link.                                 |
+| `CommandHelp`               | `help`      | `AbstractBuiltInTask`        | Show command help + the bot prefix.                          |
+| `ReportBug`                 | `help`      | `AbstractBuiltInTask`        | Start a bug-report flow / provide the report link.           |
+| `LoadPlaylistTask`          | `music`     | `ButtonTask` (with children) | Present playlist/search results as choice buttons.           |
+| `LoadTrackFromPlaylistTask` | `music`     | `ButtonTask`                 | Load one specific track from the results.                    |
+| `EmojiRoleFirstStep`        | `reaction`  | `AbstractStepTask`           | Ask for the target role id.                                  |
+| `EmojiRoleSecondStep`       | `reaction`  | `AbstractStepTask`           | Ask for the emoji to map.                                    |
+| `EmojiRoleModify`           | `reaction`  | `AbstractStepTask`           | Modify an existing emoji-role mapping.                       |
+| `EmojiRoleRemoveStep`       | `reaction`  | `AbstractStepTask`           | Remove an emoji-role mapping.                                |
+| `MusicManagerCleanup`       | `scheduled` | `ScheduledTask`              | Evict unused per-guild music managers.                       |
+| `MusicPlayerAutoDisconnect` | `scheduled` | `ScheduledTask`              | Disconnect from voice when idle.                             |
+| `TaskCleanup`               | `scheduled` | `ScheduledTask`              | Periodically remove expired non-persistable tasks.           |
+
+### Worked example — emoji-role setup (step → persistable)
+
+1. `EmojiRoleFirstStep` sends a prompt: "reply with the role id"; `AbstractStepTask` validates it is a
+   real role in the guild.
+2. `executeStep` returns `StepResult.next(new EmojiRoleSecondStep(...))`, carrying the chosen role.
+3. `EmojiRoleSecondStep` asks for the emoji; on a valid answer it creates an
+   `EmojiReactionRoleTask`.
+4. That `EmojiReactionRoleTask` is `insert`ed into `TaskManager` — because it is a
+   [persistable task](#31-persistable-tasks) it is written to the `tasks` table and will be restored
+   on the next startup via the [`persistable-tasks.json`](#the-mapping-file--persistable-tasksjson)
+   mapping.
+
+### Worked example — GitLab bug report (modal)
+
+1. `ReportIssueTask.replyToInteraction` opens a modal with **title** and **description** fields.
+2. On submit, `ModalTaskContext` routes back to the task; `execute` reads the field values.
+3. The task connects to GitLab (using `GITLAB_HOST` / `GITLAB_TOKEN` / `GITLAB_PROJECT_ID` from
+   configuration) and creates an issue, then returns `Lifecycle.REMOVE_SELF`.
+
+### Worked example — music results (parent/children)
+
+1. `LoadPlaylistTask` posts a message with a button per result (children:
+   `LoadTrackFromPlaylistTask` / `AcceptButton`).
+2. All children share the parent's lock id ([`WithParent`](#trait-interfaces)), so simultaneous
+   clicks are serialized.
+3. Selecting a result can return `REMOVE_SELF_AND_CHILDREN` to tear down the whole interaction.

docs/threading.md

@@ -0,0 +1,45 @@
+# Threading & Scheduling
+
+**Package:** `me.bobert.netneutrality.platform.concurrency`
+
+This subsystem centralizes asynchronous execution and recurring jobs.
+
+## Classes
+
+| Class | Responsibility |
+|---|---|
+| `ThreadManager` | Static registry of `ExecutorService` instances shared across the bot. |
+| `BaseThreadFactory` | Custom `ThreadFactory` giving threads meaningful names and an uncaught-exception handler. |
+| `ScheduledTaskManager` | Schedules and cancels recurring [scheduled tasks](tasks.md#34-scheduled-tasks). |
+
+## `ThreadManager`
+
+- `getScheduledExecutor()` — a `ScheduledThreadPool` sized to the number of CPU cores.
+- `getExecutor(name)` — returns (and caches) a named thread pool for ad-hoc async work.
+- `shutdownExecutor()` — shuts the executors down cleanly; called from
+  [`App.shutdown()`](architecture.md#shutdown-lifecycle).
+
+## `BaseThreadFactory`
+
+Names created threads (e.g. `web-api-1`) so they are identifiable in logs and stack dumps, and installs
+an [`ExecutorException`](utilities-and-bootstrap.md#exceptions) as the thread's
+`UncaughtExceptionHandler` so crashes on worker threads are still routed through
+[`LogHandler`](utilities-and-bootstrap.md#loghandler). It is used both by `ThreadManager` and by the
+[Web API](web-api.md) server pool.
+
+## `ScheduledTaskManager`
+
+Coordinates [`ScheduledTask`](tasks.md#34-scheduled-tasks) instances (discovered reflectively at
+startup by [`TaskManager.init()`](tasks.md#taskmanager)):
+
+- `schedule(ScheduledTask task)` — schedules the task at a fixed delay/interval derived from its
+  `TimeFrame` (minutely / hourly / daily / custom), using the shared scheduled executor.
+- `cancelAll()` — cancels every scheduled task; called first in
+  [`App.shutdown()`](architecture.md#shutdown-lifecycle).
+
+The existing scheduled tasks are `MusicManagerCleanup`, `MusicPlayerAutoDisconnect`, and
+`TaskCleanup` (see the [task catalog](tasks.md#concrete-task-catalog)).
+
+> **Direction of travel:** the scheduled-task abstraction is intended to eventually replace ad-hoc
+> threads created via `ThreadManager`, giving a single, uniform way to express recurring background
+> work. It is still evolving (see [tasks.md §3.4](tasks.md#34-scheduled-tasks)).

docs/utilities-and-bootstrap.md

@@ -0,0 +1,164 @@
+# Utilities, Bootstrap, Logging & Exceptions
+
+This document covers the cross-cutting glue of the bot: the entry points, configuration, logging /
+error tracking, the shared utility helpers, and the custom exception hierarchy.
+
+## Bootstrap
+
+**Package:** `me.bobert.netneutrality` / `me.bobert.netneutrality.bootstrap`
+
+| Class | Role |
+|---|---|
+| `App` | The application: holds the process instance and the `JDA` handle, builds the `ApplicationContext`, runs `context.start()` / `context.stop()`, and is the JAR main class (`main()`). See [architecture.md](architecture.md). |
+| `bootstrap.ApplicationContext` | Hand-rolled container: `register(T)`, `get(Class<T>)`, ordered `start()` / `stop()` for `Lifecycle` components. |
+| `bootstrap.Lifecycle` | Optional component contract: `start() throws Exception`, default `stop()`, default `priority()`. |
+| `NetNeutralityBot` | Currently an **empty placeholder** class under `framework` (reserved name; no logic yet). |
+| `core.BotState` | Work-in-progress global state helper: exposes a `SAFE` flag and `dump()`, which serializes per-guild/music state to `state.json`. Bound to `GuildServiceProvider` / `MusicService` during bootstrap. |
+
+The full startup and shutdown sequences are documented in
+[architecture.md](architecture.md#startup-lifecycle).
+
+### `ApplicationContext` + `Lifecycle`
+
+Domain services are constructed once in `App.buildContext()`, registered with the context,
+and resolved later by type:
+
+- `register(component)` — indexes the concrete class; if the component implements `Lifecycle` it
+  participates in ordered start/stop.
+- `get(Class<T>)` — returns the first registered instance assignable to `T` (interfaces work).
+- `start()` — sorts `Lifecycle` components by ascending `priority()` and starts them.
+- `stop()` — stops them in the exact reverse order; individual failures are logged and swallowed so
+  remaining components still tear down.
+
+Constructor injection for reflectively loaded commands/tasks is handled by
+[`ReflectionHelper`](#reflectionhelper): the richest public constructor whose parameter types all
+resolve via `context.get(type)` is preferred; otherwise the no-arg constructor is used.
+
+**Interfaces used for injection** (implemented by the concrete managers registered above):
+
+| Interface | Typical implementor |
+|---|---|
+| `platform.config.SettingsProvider` | `utils.Settings` |
+| `platform.persistence.SessionProvider` | `core.db.SessionManager` |
+| `platform.concurrency.ExecutorProvider` | `core.thread.ThreadManager` |
+| `framework.command.CommandRegistry` | `core.command.CommandManager` |
+| `framework.task.TaskManager` | `core.tasks.TaskManagerImpl` |
+| `feature.music.MusicService` | `music.MusicServiceImpl` |
+| `data.service.GuildServiceProvider` | `db.service.GuildServiceProviderImpl` |
+
+There are **no** `getInstance()` / `instance()` shims on the managers above. The only intentional
+static access points left are:
+
+- `Settings.getInstance()` — early bootstrap only (`main()`, Sentry, token validation) before the
+  context exists; the same instance is registered as `SettingsProvider` for everything else.
+- `App.getInstance()` — application root used by a couple of shutdown entry points
+  (`ShutdownCommand`). Prefer constructor injection of the needed collaborators where possible.
+- `JpaUtils.bind(SessionProvider)` / `LogHandler.bind(GuildServiceProvider)` /
+  `ChannelMessagePurger.bind(ExecutorProvider)` — single well-defined static bind points for deep
+  utility graphs that are not constructor-injected (repositories, static log helpers).
+
+## Configuration
+
+### `Settings` / `SettingsProvider`
+
+**Class:** `me.bobert.netneutrality.platform.config.Settings` implements
+`me.bobert.netneutrality.platform.config.SettingsProvider`.
+
+`Settings` is the single source of truth for configuration. It loads values from the `bot.properties`
+file and overlays **environment variables** on top (environment variables win).
+
+- **Early bootstrap:** `Settings.getInstance()` (process-wide, created once before the context).
+- **Runtime injection:** depend on `SettingsProvider` and let `ApplicationContext` supply the same
+  instance. Prefer this path in commands, tasks, handlers, and services.
+- `Settings.getVersion()` / `Settings.getDiscordInvite()` — thin static helpers used by the banner /
+  invite strings; they delegate to the bootstrap instance.
+
+An example configuration file is `bot.properties.example`. Key configuration values:
+
+| Key | Purpose |
+|---|---|
+| `NETNEUTRALITY_BOT_ENV` | `dev` / `prod`; controls debug logging and the Sentry environment. |
+| `NETNEUTRALITY_BOT_TOKEN` | Discord bot token (**required**). |
+| `NETNEUTRALITY_BOT_PREFIX` | Message-command prefix (default `$`). |
+| `NETNEUTRALITY_BOT_OWNER` | Bot owner user id (used for owner-only commands / permissions). |
+| `NETNEUTRALITY_BOT_INVITE` | Invite link surfaced by help/info. |
+| `NETNEUTRALITY_API_PORT` | Port for the [Web API](web-api.md) (default `9000`). |
+| `MYSQL_*` | Database connection settings (see [persistence.md](persistence.md)). |
+| `NETNEUTRALITY_SENTRY_DSN` | Enables Sentry when present. |
+| `GITLAB_HOST` / `GITLAB_TOKEN` / `GITLAB_PROJECT_ID` | GitLab issue reporting ([`ReportIssueTask`](tasks.md#worked-example--gitlab-bug-report-modal)). |
+| `NETNEUTRALITY_PO_TOKEN` / `NETNEUTRALITY_VISITOR_DATA` / `NETNEUTRALITY_CIPHER_*` | YouTube playback auth/cipher settings for the [music](music.md) source. |
+
+## Utility helpers
+
+**Package:** `me.bobert.netneutrality.shared.util` (helpers) / `me.bobert.netneutrality.bootstrap` / `me.bobert.netneutrality.platform.*`
+
+| Class | Purpose |
+|---|---|
+| `Settings` | Configuration (see above). |
+| `ReflectionHelper` | Classpath scanning / reflective instantiation (see below). |
+| `ContextUtils` | Boilerplate helpers for building/handling [contexts](contexts.md). |
+| `GuildUtils` | Guild-related helpers (lookups, permission checks). |
+| `JpaUtils` | Session/transaction helpers for the [persistence](persistence.md) layer. Bound once to a `SessionProvider` during bootstrap (`JpaUtils.bind`). |
+| `MusicUtils` | Voice-channel connectivity and DJ/permission checks for [music](music.md). Callers pass the guild `MusicManager` (no static music lookup). |
+| `MiscUtils` | Assorted small helpers. |
+| `ChannelMessagePurger` | Bulk message deletion (used by the purge command). Bound once to an `ExecutorProvider` during bootstrap. |
+| `MessageFunction` | Standardized message/embed formatting. Help text builders take a `CommandRegistry` rather than a static command manager. |
+| `UserFunction` | Standardized user/string formatting. |
+
+### `ReflectionHelper`
+
+Built on the `org.reflections` library, `ReflectionHelper` discovers and instantiates implementation
+classes in specific packages. It is the mechanism behind the bot's "drop a class in the right package
+and it's picked up" model, used to auto-load:
+
+- [`Command`](commands.md) implementations (`CommandManager` / `CommandRegistry.start()`),
+- [`BuiltInTask`](tasks.md#32-built-in-tasks) and [`ScheduledTask`](tasks.md#34-scheduled-tasks)
+  implementations (`TaskManager.start()`).
+
+When given an `ApplicationContext`, `newInstance(Class, ApplicationContext)` selects the public
+constructor with the most parameters that can all be resolved via `context.get(parameterType)`. If
+no such constructor exists it falls back to the no-arg constructor. That is how music/admin/react
+commands receive `MusicService`, `GuildServiceProvider`, `TaskManager`, etc. without static
+singletons.
+
+## Logging & error tracking
+
+### `LogHandler`
+
+**Class:** `me.bobert.netneutrality.platform.logging.LogHandler`.
+
+`LogHandler` is the unified logging/error entry point. It routes messages and exceptions to:
+
+1. **Log4j2** (configured by `log4j2.properties`; SLF4J is bridged via `log4j-slf4j2-impl`),
+2. **Sentry** (when `NETNEUTRALITY_SENTRY_DSN` is configured), and
+3. optionally a per-guild **Discord debug channel** (e.g. `sendMessageToDebugChannel(guild, msg)`),
+   gated by [`GuildService.isDebugEnabled()`](persistence.md#service-layer) /
+   [`OLogging`](persistence.md#entity-catalog) configuration.
+
+The Sentry **user** context is attached automatically when a
+[`AbstractContext`](contexts.md#abstractcontext-abstract-class) is created, so captured errors are
+attributed to the Discord user that triggered them.
+
+## Exception hierarchy
+
+**Package:** `me.bobert.netneutrality.exceptions`
+
+```
+RuntimeException
+└── ContextException                 ── carries a Context (guild/channel/user)
+    ├── CommandExecutionException    ── thrown during command processing
+    └── TaskExecutionException       ── thrown during task execution
+
+GracefulContextError                 ── user-facing, non-logged failure → ephemeral reply
+ExecutorException                    ── Thread.UncaughtExceptionHandler → routes crashes to LogHandler
+```
+
+- **`ContextException`** — base runtime exception that carries the [`Context`](contexts.md) in which
+  it occurred, so downstream handling can respond in the right channel and attribute the error.
+- **`CommandExecutionException`** / **`TaskExecutionException`** — specializations thrown by the
+  [command](commands.md) and [task](tasks.md) flows respectively.
+- **`GracefulContextError`** — signals an expected, user-facing problem (e.g. bad input); when caught
+  it produces an ephemeral message to the user instead of a full error log/Sentry event.
+- **`ExecutorException`** — an `UncaughtExceptionHandler` installed by
+  [`BaseThreadFactory`](threading.md#basethreadfactory) so exceptions escaping worker threads are still
+  captured by [`LogHandler`](#loghandler).

docs/web-api.md

@@ -0,0 +1,51 @@
+# HTTP Web API
+
+**Package:** `me.bobert.netneutrality.platform.web` (client module) and
+`me.bobert.netneutrality.platform.web.server` (server).
+**Server:** JDK built-in `com.sun.net.httpserver.HttpServer` (no external web framework).
+
+The bot exposes a small internal HTTP API for health monitoring, control, and guild introspection —
+intended for an external dashboard/companion, not for end users in Discord.
+
+## Server startup
+
+`WebApi` is a [`Lifecycle`](utilities-and-bootstrap.md#applicationcontext--lifecycle) component
+(priority 70) registered in [`App.buildContext()`](architecture.md#startup-lifecycle).
+It receives `SettingsProvider`, `GuildServiceProvider`, and suppliers for the live `JDA` /
+shutdown callback via its constructor. On `start()` it:
+
+- reads the port from `NETNEUTRALITY_API_PORT` (default `9000`),
+- creates an `HttpServer` bound to that port,
+- installs an `Executor` backed by a fixed thread pool of 10 threads named via
+  [`BaseThreadFactory`](threading.md),
+- registers the handler contexts (below), and
+- starts the server.
+
+On `stop()` the server and its executor are shut down gracefully.
+
+## Handler model
+
+`AbstractHandler` (implements `HttpHandler`) is the base for all handlers and provides helpers such as
+`sendJsonResponse(...)` and `sendStringResponse(...)`. Concrete handlers extend it and are mounted at
+a path prefix.
+
+| Handler | Base path | Endpoints |
+|---|---|---|
+| `RootHandler` | `/` | Simple HTML "OK" landing response. |
+| `GuildHandler` | `/guilds` | `/guilds/owner` — guild ids + owner ids (JSON); `/guilds/channels/{guildId}` — text channels (JSON); `/guilds/roles/{guildId}` — roles (JSON). |
+| `ActionHandler` | `/actions` | `/actions/status` — JDA health + gateway ping; `/actions/shutdown` — graceful shutdown; `/actions/settings/current/{guildId}` — current guild settings; `/actions/settings/reload/{guildId}` — invalidate & reload the settings cache. |
+
+The action/guild handlers read live state from the [`JDA`](architecture.md) instance and from the
+[persistence services](persistence.md#service-layer) (e.g. `GuildSettingService` for the settings
+endpoints).
+
+## HTTP client — `WebModule`
+
+`WebModule` wraps an `OkHttpClient` for the bot's own outbound HTTP calls (e.g. checking for updates
+via GitLab). It keeps a small `LinkedHashMap`-based response cache limited to 50 entries.
+
+## Notes
+
+- There is no authentication layer documented on these endpoints; the API is expected to be bound to a
+  trusted/internal network (e.g. within the Docker network). `/actions/shutdown` is destructive, so the
+  port should not be exposed publicly.

flyway-dev.ps1

@@ -0,0 +1,42 @@
+param (
+    [ValidateSet("migrate", "info", "validate", "clean", "baseline", "repair")]
+    [string]$Command = "info"
+)
+
+$envFile = ".env"
+if (-not (Test-Path $envFile)) {
+    Write-Error ".env file not found in the current directory."
+    exit 1
+}
+
+Get-Content $envFile | ForEach-Object {
+    if ($_ -match "^\s*([A-Za-z_][A-Za-z0-9_]*)=(.*)$") {
+        $name = $matches[1]
+        $value = $matches[2]
+        [System.Environment]::SetEnvironmentVariable($name, $value)
+    }
+}
+
+$MYSQL_HOST = $env:MYSQL_HOST
+$MYSQL_PORT = $env:MYSQL_PORT
+$MYSQL_DATABASE = $env:MYSQL_DATABASE
+
+if (-not $MYSQL_HOST -or -not $MYSQL_PORT -or -not $MYSQL_DATABASE) {
+    Write-Error "MYSQL_HOST, MYSQL_PORT, or MYSQL_DATABASE missing from .env"
+    exit 1
+}
+
+$env:FLYWAY_URL = "jdbc:mysql://${MYSQL_HOST}:${MYSQL_PORT}/${MYSQL_DATABASE}"
+$env:FLYWAY_USER = $env:MYSQL_USER
+$env:FLYWAY_PASSWORD = $env:MYSQL_PASSWORD
+
+Write-Host "Ensuring database '$MYSQL_DATABASE' exists..."
+$mysqlCommand = "CREATE DATABASE IF NOT EXISTS $MYSQL_DATABASE CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
+& mysql --host=$MYSQL_HOST --port=$MYSQL_PORT --user=$env:MYSQL_USER --password=$env:MYSQL_PASSWORD -e $mysqlCommand
+
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "Failed to create database or connect to MySQL. Check your credentials or server status."
+    exit 1
+}
+
+.\mvnw flyway:$Command

flyway-dev.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+set -e
+
+COMMAND=${1:-info}
+ENV_FILE=".env"
+
+if [[ ! -f "$ENV_FILE" ]]; then
+  echo ".env file not found in the current directory."
+  exit 1
+fi
+
+# Export variables from .env
+export $(grep -E '^[A-Za-z_][A-Za-z0-9_]*=' "$ENV_FILE" | xargs)
+
+if [[ -z "$MYSQL_HOST" || -z "$MYSQL_PORT" || -z "$MYSQL_DATABASE" ]]; then
+  echo "MYSQL_HOST, MYSQL_PORT, or MYSQL_DATABASE missing from .env"
+  exit 1
+fi
+
+export FLYWAY_URL="jdbc:mysql://${MYSQL_HOST}:${MYSQL_PORT}/${MYSQL_DATABASE}"
+export FLYWAY_USER="$MYSQL_USER"
+export FLYWAY_PASSWORD="$MYSQL_PASSWORD"
+
+echo "Ensuring database '$MYSQL_DATABASE' exists..."
+mysql -h"$MYSQL_HOST" -P"$MYSQL_PORT" -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" \
+  -e "CREATE DATABASE IF NOT EXISTS \`$MYSQL_DATABASE\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
+
+if [[ $? -ne 0 ]]; then
+  echo "Failed to create database or connect to MySQL. Check your credentials or server status."
+  exit 1
+fi
+
+./mvnw flyway:"$COMMAND"

mvnw

@@ -19,290 +19,277 @@
 # ----------------------------------------------------------------------------
 
 # ----------------------------------------------------------------------------
-# Apache Maven Wrapper startup batch script, version 3.2.0
+# Apache Maven Wrapper startup batch script, version 3.3.4
-#
-# Required ENV vars:
-# ------------------
-#   JAVA_HOME - location of a JDK home dir
 #
 # Optional ENV vars
 # -----------------
-#   MAVEN_OPTS - parameters passed to the Java VM when running Maven
+#   JAVA_HOME - location of a JDK home dir, required when download maven via java source
-#     e.g. to debug Maven itself, use
+#   MVNW_REPOURL - repo url base for downloading maven distribution
-#       set MAVEN_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000
+#   MVNW_USERNAME/MVNW_PASSWORD - user and password for downloading maven
-#   MAVEN_SKIP_RC - flag to disable loading of mavenrc files
+#   MVNW_VERBOSE - true: enable verbose log; debug: trace the mvnw script; others: silence the output
 # ----------------------------------------------------------------------------
 
-if [ -z "$MAVEN_SKIP_RC" ] ; then
+set -euf
+[ "${MVNW_VERBOSE-}" != debug ] || set -x
 
-  if [ -f /usr/local/etc/mavenrc ] ; then
+# OS specific support.
-    . /usr/local/etc/mavenrc
+native_path() { printf %s\\n "$1"; }
-  fi
-
-  if [ -f /etc/mavenrc ] ; then
-    . /etc/mavenrc
-  fi
-
-  if [ -f "$HOME/.mavenrc" ] ; then
-    . "$HOME/.mavenrc"
-  fi
-
-fi
-
-# OS specific support.  $var _must_ be set to either true or false.
-cygwin=false;
-darwin=false;
-mingw=false
 case "$(uname)" in
-  CYGWIN*) cygwin=true ;;
+CYGWIN* | MINGW*)
-  MINGW*) mingw=true;;
+  [ -z "${JAVA_HOME-}" ] || JAVA_HOME="$(cygpath --unix "$JAVA_HOME")"
-  Darwin*) darwin=true
+  native_path() { cygpath --path --windows "$1"; }
-    # Use /usr/libexec/java_home if available, otherwise fall back to /Library/Java/Home
+  ;;
-    # See https://developer.apple.com/library/mac/qa/qa1170/_index.html
-    if [ -z "$JAVA_HOME" ]; then
-      if [ -x "/usr/libexec/java_home" ]; then
-        JAVA_HOME="$(/usr/libexec/java_home)"; export JAVA_HOME
-      else
-        JAVA_HOME="/Library/Java/Home"; export JAVA_HOME
-      fi
-    fi
-    ;;
 esac
 
-if [ -z "$JAVA_HOME" ] ; then
+# set JAVACMD and JAVACCMD
-  if [ -r /etc/gentoo-release ] ; then
+set_java_home() {
-    JAVA_HOME=$(java-config --jre-home)
+  # For Cygwin and MinGW, ensure paths are in Unix format before anything is touched
-  fi
+  if [ -n "${JAVA_HOME-}" ]; then
-fi
+    if [ -x "$JAVA_HOME/jre/sh/java" ]; then
-
-# For Cygwin, ensure paths are in UNIX format before anything is touched
-if $cygwin ; then
-  [ -n "$JAVA_HOME" ] &&
-    JAVA_HOME=$(cygpath --unix "$JAVA_HOME")
-  [ -n "$CLASSPATH" ] &&
-    CLASSPATH=$(cygpath --path --unix "$CLASSPATH")
-fi
-
-# For Mingw, ensure paths are in UNIX format before anything is touched
-if $mingw ; then
-  [ -n "$JAVA_HOME" ] && [ -d "$JAVA_HOME" ] &&
-    JAVA_HOME="$(cd "$JAVA_HOME" || (echo "cannot cd into $JAVA_HOME."; exit 1); pwd)"
-fi
-
-if [ -z "$JAVA_HOME" ]; then
-  javaExecutable="$(which javac)"
-  if [ -n "$javaExecutable" ] && ! [ "$(expr "\"$javaExecutable\"" : '\([^ ]*\)')" = "no" ]; then
-    # readlink(1) is not available as standard on Solaris 10.
-    readLink=$(which readlink)
-    if [ ! "$(expr "$readLink" : '\([^ ]*\)')" = "no" ]; then
-      if $darwin ; then
-        javaHome="$(dirname "\"$javaExecutable\"")"
-        javaExecutable="$(cd "\"$javaHome\"" && pwd -P)/javac"
-      else
-        javaExecutable="$(readlink -f "\"$javaExecutable\"")"
-      fi
-      javaHome="$(dirname "\"$javaExecutable\"")"
-      javaHome=$(expr "$javaHome" : '\(.*\)/bin')
-      JAVA_HOME="$javaHome"
-      export JAVA_HOME
-    fi
-  fi
-fi
-
-if [ -z "$JAVACMD" ] ; then
-  if [ -n "$JAVA_HOME"  ] ; then
-    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
       # IBM's JDK on AIX uses strange locations for the executables
       JAVACMD="$JAVA_HOME/jre/sh/java"
+      JAVACCMD="$JAVA_HOME/jre/sh/javac"
     else
       JAVACMD="$JAVA_HOME/bin/java"
+      JAVACCMD="$JAVA_HOME/bin/javac"
+
+      if [ ! -x "$JAVACMD" ] || [ ! -x "$JAVACCMD" ]; then
+        echo "The JAVA_HOME environment variable is not defined correctly, so mvnw cannot run." >&2
+        echo "JAVA_HOME is set to \"$JAVA_HOME\", but \"\$JAVA_HOME/bin/java\" or \"\$JAVA_HOME/bin/javac\" does not exist." >&2
+        return 1
+      fi
     fi
   else
-    JAVACMD="$(\unset -f command 2>/dev/null; \command -v java)"
+    JAVACMD="$(
-  fi
+      'set' +e
-fi
+      'unset' -f command 2>/dev/null
+      'command' -v java
+    )" || :
+    JAVACCMD="$(
+      'set' +e
+      'unset' -f command 2>/dev/null
+      'command' -v javac
+    )" || :
 
-if [ ! -x "$JAVACMD" ] ; then
+    if [ ! -x "${JAVACMD-}" ] || [ ! -x "${JAVACCMD-}" ]; then
-  echo "Error: JAVA_HOME is not defined correctly." >&2
+      echo "The java/javac command does not exist in PATH nor is JAVA_HOME set, so mvnw cannot run." >&2
-  echo "  We cannot execute $JAVACMD" >&2
+      return 1
-  exit 1
-fi
-
-if [ -z "$JAVA_HOME" ] ; then
-  echo "Warning: JAVA_HOME environment variable is not set."
-fi
-
-# traverses directory structure from process work directory to filesystem root
-# first directory with .mvn subdirectory is considered project base directory
-find_maven_basedir() {
-  if [ -z "$1" ]
-  then
-    echo "Path not specified to find_maven_basedir"
-    return 1
-  fi
-
-  basedir="$1"
-  wdir="$1"
-  while [ "$wdir" != '/' ] ; do
-    if [ -d "$wdir"/.mvn ] ; then
-      basedir=$wdir
-      break
     fi
-    # workaround for JBEAP-8937 (on Solaris 10/Sparc)
+  fi
-    if [ -d "${wdir}" ]; then
+}
-      wdir=$(cd "$wdir/.." || exit 1; pwd)
+
-    fi
+# hash string like Java String::hashCode
-    # end of workaround
+hash_string() {
+  str="${1:-}" h=0
+  while [ -n "$str" ]; do
+    char="${str%"${str#?}"}"
+    h=$(((h * 31 + $(LC_CTYPE=C printf %d "'$char")) % 4294967296))
+    str="${str#?}"
   done
-  printf '%s' "$(cd "$basedir" || exit 1; pwd)"
+  printf %x\\n $h
 }
 
-# concatenates all lines of a file
+verbose() { :; }
-concat_lines() {
+[ "${MVNW_VERBOSE-}" != true ] || verbose() { printf %s\\n "${1-}"; }
-  if [ -f "$1" ]; then
+
-    # Remove \r in case we run on Windows within Git Bash
+die() {
-    # and check out the repository with auto CRLF management
+  printf %s\\n "$1" >&2
-    # enabled. Otherwise, we may read lines that are delimited with
+  exit 1
-    # \r\n and produce $'-Xarg\r' rather than -Xarg due to word
-    # splitting rules.
-    tr -s '\r\n' ' ' < "$1"
-  fi
 }
 
-log() {
+trim() {
-  if [ "$MVNW_VERBOSE" = true ]; then
+  # MWRAPPER-139:
-    printf '%s\n' "$1"
+  #   Trims trailing and leading whitespace, carriage returns, tabs, and linefeeds.
-  fi
+  #   Needed for removing poorly interpreted newline sequences when running in more
+  #   exotic environments such as mingw bash on Windows.
+  printf "%s" "${1}" | tr -d '[:space:]'
 }
 
-BASE_DIR=$(find_maven_basedir "$(dirname "$0")")
+scriptDir="$(dirname "$0")"
-if [ -z "$BASE_DIR" ]; then
+scriptName="$(basename "$0")"
-  exit 1;
-fi
 
-MAVEN_PROJECTBASEDIR=${MAVEN_BASEDIR:-"$BASE_DIR"}; export MAVEN_PROJECTBASEDIR
+# parse distributionUrl and optional distributionSha256Sum, requires .mvn/wrapper/maven-wrapper.properties
-log "$MAVEN_PROJECTBASEDIR"
-
-##########################################################################################
-# Extension to allow automatically downloading the maven-wrapper.jar from Maven-central
-# This allows using the maven wrapper in projects that prohibit checking in binary data.
-##########################################################################################
-wrapperJarPath="$MAVEN_PROJECTBASEDIR/.mvn/wrapper/maven-wrapper.jar"
-if [ -r "$wrapperJarPath" ]; then
-    log "Found $wrapperJarPath"
-else
-    log "Couldn't find $wrapperJarPath, downloading it ..."
-
-    if [ -n "$MVNW_REPOURL" ]; then
-      wrapperUrl="$MVNW_REPOURL/org/apache/maven/wrapper/maven-wrapper/3.2.0/maven-wrapper-3.2.0.jar"
-    else
-      wrapperUrl="https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.2.0/maven-wrapper-3.2.0.jar"
-    fi
-    while IFS="=" read -r key value; do
-      # Remove '\r' from value to allow usage on windows as IFS does not consider '\r' as a separator ( considers space, tab, new line ('\n'), and custom '=' )
-      safeValue=$(echo "$value" | tr -d '\r')
-      case "$key" in (wrapperUrl) wrapperUrl="$safeValue"; break ;;
-      esac
-    done < "$MAVEN_PROJECTBASEDIR/.mvn/wrapper/maven-wrapper.properties"
-    log "Downloading from: $wrapperUrl"
-
-    if $cygwin; then
-      wrapperJarPath=$(cygpath --path --windows "$wrapperJarPath")
-    fi
-
-    if command -v wget > /dev/null; then
-        log "Found wget ... using wget"
-        [ "$MVNW_VERBOSE" = true ] && QUIET="" || QUIET="--quiet"
-        if [ -z "$MVNW_USERNAME" ] || [ -z "$MVNW_PASSWORD" ]; then
-            wget $QUIET "$wrapperUrl" -O "$wrapperJarPath" || rm -f "$wrapperJarPath"
-        else
-            wget $QUIET --http-user="$MVNW_USERNAME" --http-password="$MVNW_PASSWORD" "$wrapperUrl" -O "$wrapperJarPath" || rm -f "$wrapperJarPath"
-        fi
-    elif command -v curl > /dev/null; then
-        log "Found curl ... using curl"
-        [ "$MVNW_VERBOSE" = true ] && QUIET="" || QUIET="--silent"
-        if [ -z "$MVNW_USERNAME" ] || [ -z "$MVNW_PASSWORD" ]; then
-            curl $QUIET -o "$wrapperJarPath" "$wrapperUrl" -f -L || rm -f "$wrapperJarPath"
-        else
-            curl $QUIET --user "$MVNW_USERNAME:$MVNW_PASSWORD" -o "$wrapperJarPath" "$wrapperUrl" -f -L || rm -f "$wrapperJarPath"
-        fi
-    else
-        log "Falling back to using Java to download"
-        javaSource="$MAVEN_PROJECTBASEDIR/.mvn/wrapper/MavenWrapperDownloader.java"
-        javaClass="$MAVEN_PROJECTBASEDIR/.mvn/wrapper/MavenWrapperDownloader.class"
-        # For Cygwin, switch paths to Windows format before running javac
-        if $cygwin; then
-          javaSource=$(cygpath --path --windows "$javaSource")
-          javaClass=$(cygpath --path --windows "$javaClass")
-        fi
-        if [ -e "$javaSource" ]; then
-            if [ ! -e "$javaClass" ]; then
-                log " - Compiling MavenWrapperDownloader.java ..."
-                ("$JAVA_HOME/bin/javac" "$javaSource")
-            fi
-            if [ -e "$javaClass" ]; then
-                log " - Running MavenWrapperDownloader.java ..."
-                ("$JAVA_HOME/bin/java" -cp .mvn/wrapper MavenWrapperDownloader "$wrapperUrl" "$wrapperJarPath") || rm -f "$wrapperJarPath"
-            fi
-        fi
-    fi
-fi
-##########################################################################################
-# End of extension
-##########################################################################################
-
-# If specified, validate the SHA-256 sum of the Maven wrapper jar file
-wrapperSha256Sum=""
 while IFS="=" read -r key value; do
-  case "$key" in (wrapperSha256Sum) wrapperSha256Sum=$value; break ;;
+  case "${key-}" in
+  distributionUrl) distributionUrl=$(trim "${value-}") ;;
+  distributionSha256Sum) distributionSha256Sum=$(trim "${value-}") ;;
   esac
-done < "$MAVEN_PROJECTBASEDIR/.mvn/wrapper/maven-wrapper.properties"
+done <"$scriptDir/.mvn/wrapper/maven-wrapper.properties"
-if [ -n "$wrapperSha256Sum" ]; then
+[ -n "${distributionUrl-}" ] || die "cannot read distributionUrl property in $scriptDir/.mvn/wrapper/maven-wrapper.properties"
-  wrapperSha256Result=false
+
-  if command -v sha256sum > /dev/null; then
+case "${distributionUrl##*/}" in
-    if echo "$wrapperSha256Sum  $wrapperJarPath" | sha256sum -c > /dev/null 2>&1; then
+maven-mvnd-*bin.*)
-      wrapperSha256Result=true
+  MVN_CMD=mvnd.sh _MVNW_REPO_PATTERN=/maven/mvnd/
+  case "${PROCESSOR_ARCHITECTURE-}${PROCESSOR_ARCHITEW6432-}:$(uname -a)" in
+  *AMD64:CYGWIN* | *AMD64:MINGW*) distributionPlatform=windows-amd64 ;;
+  :Darwin*x86_64) distributionPlatform=darwin-amd64 ;;
+  :Darwin*arm64) distributionPlatform=darwin-aarch64 ;;
+  :Linux*x86_64*) distributionPlatform=linux-amd64 ;;
+  *)
+    echo "Cannot detect native platform for mvnd on $(uname)-$(uname -m), use pure java version" >&2
+    distributionPlatform=linux-amd64
+    ;;
+  esac
+  distributionUrl="${distributionUrl%-bin.*}-$distributionPlatform.zip"
+  ;;
+maven-mvnd-*) MVN_CMD=mvnd.sh _MVNW_REPO_PATTERN=/maven/mvnd/ ;;
+*) MVN_CMD="mvn${scriptName#mvnw}" _MVNW_REPO_PATTERN=/org/apache/maven/ ;;
+esac
+
+# apply MVNW_REPOURL and calculate MAVEN_HOME
+# maven home pattern: ~/.m2/wrapper/dists/{apache-maven-<version>,maven-mvnd-<version>-<platform>}/<hash>
+[ -z "${MVNW_REPOURL-}" ] || distributionUrl="$MVNW_REPOURL$_MVNW_REPO_PATTERN${distributionUrl#*"$_MVNW_REPO_PATTERN"}"
+distributionUrlName="${distributionUrl##*/}"
+distributionUrlNameMain="${distributionUrlName%.*}"
+distributionUrlNameMain="${distributionUrlNameMain%-bin}"
+MAVEN_USER_HOME="${MAVEN_USER_HOME:-${HOME}/.m2}"
+MAVEN_HOME="${MAVEN_USER_HOME}/wrapper/dists/${distributionUrlNameMain-}/$(hash_string "$distributionUrl")"
+
+exec_maven() {
+  unset MVNW_VERBOSE MVNW_USERNAME MVNW_PASSWORD MVNW_REPOURL || :
+  exec "$MAVEN_HOME/bin/$MVN_CMD" "$@" || die "cannot exec $MAVEN_HOME/bin/$MVN_CMD"
+}
+
+if [ -d "$MAVEN_HOME" ]; then
+  verbose "found existing MAVEN_HOME at $MAVEN_HOME"
+  exec_maven "$@"
+fi
+
+case "${distributionUrl-}" in
+*?-bin.zip | *?maven-mvnd-?*-?*.zip) ;;
+*) die "distributionUrl is not valid, must match *-bin.zip or maven-mvnd-*.zip, but found '${distributionUrl-}'" ;;
+esac
+
+# prepare tmp dir
+if TMP_DOWNLOAD_DIR="$(mktemp -d)" && [ -d "$TMP_DOWNLOAD_DIR" ]; then
+  clean() { rm -rf -- "$TMP_DOWNLOAD_DIR"; }
+  trap clean HUP INT TERM EXIT
+else
+  die "cannot create temp dir"
+fi
+
+mkdir -p -- "${MAVEN_HOME%/*}"
+
+# Download and Install Apache Maven
+verbose "Couldn't find MAVEN_HOME, downloading and installing it ..."
+verbose "Downloading from: $distributionUrl"
+verbose "Downloading to: $TMP_DOWNLOAD_DIR/$distributionUrlName"
+
+# select .zip or .tar.gz
+if ! command -v unzip >/dev/null; then
+  distributionUrl="${distributionUrl%.zip}.tar.gz"
+  distributionUrlName="${distributionUrl##*/}"
+fi
+
+# verbose opt
+__MVNW_QUIET_WGET=--quiet __MVNW_QUIET_CURL=--silent __MVNW_QUIET_UNZIP=-q __MVNW_QUIET_TAR=''
+[ "${MVNW_VERBOSE-}" != true ] || __MVNW_QUIET_WGET='' __MVNW_QUIET_CURL='' __MVNW_QUIET_UNZIP='' __MVNW_QUIET_TAR=v
+
+# normalize http auth
+case "${MVNW_PASSWORD:+has-password}" in
+'') MVNW_USERNAME='' MVNW_PASSWORD='' ;;
+has-password) [ -n "${MVNW_USERNAME-}" ] || MVNW_USERNAME='' MVNW_PASSWORD='' ;;
+esac
+
+if [ -z "${MVNW_USERNAME-}" ] && command -v wget >/dev/null; then
+  verbose "Found wget ... using wget"
+  wget ${__MVNW_QUIET_WGET:+"$__MVNW_QUIET_WGET"} "$distributionUrl" -O "$TMP_DOWNLOAD_DIR/$distributionUrlName" || die "wget: Failed to fetch $distributionUrl"
+elif [ -z "${MVNW_USERNAME-}" ] && command -v curl >/dev/null; then
+  verbose "Found curl ... using curl"
+  curl ${__MVNW_QUIET_CURL:+"$__MVNW_QUIET_CURL"} -f -L -o "$TMP_DOWNLOAD_DIR/$distributionUrlName" "$distributionUrl" || die "curl: Failed to fetch $distributionUrl"
+elif set_java_home; then
+  verbose "Falling back to use Java to download"
+  javaSource="$TMP_DOWNLOAD_DIR/Downloader.java"
+  targetZip="$TMP_DOWNLOAD_DIR/$distributionUrlName"
+  cat >"$javaSource" <<-END
+	public class Downloader extends java.net.Authenticator
+	{
+	  protected java.net.PasswordAuthentication getPasswordAuthentication()
+	  {
+	    return new java.net.PasswordAuthentication( System.getenv( "MVNW_USERNAME" ), System.getenv( "MVNW_PASSWORD" ).toCharArray() );
+	  }
+	  public static void main( String[] args ) throws Exception
+	  {
+	    setDefault( new Downloader() );
+	    java.nio.file.Files.copy( java.net.URI.create( args[0] ).toURL().openStream(), java.nio.file.Paths.get( args[1] ).toAbsolutePath().normalize() );
+	  }
+	}
+	END
+  # For Cygwin/MinGW, switch paths to Windows format before running javac and java
+  verbose " - Compiling Downloader.java ..."
+  "$(native_path "$JAVACCMD")" "$(native_path "$javaSource")" || die "Failed to compile Downloader.java"
+  verbose " - Running Downloader.java ..."
+  "$(native_path "$JAVACMD")" -cp "$(native_path "$TMP_DOWNLOAD_DIR")" Downloader "$distributionUrl" "$(native_path "$targetZip")"
+fi
+
+# If specified, validate the SHA-256 sum of the Maven distribution zip file
+if [ -n "${distributionSha256Sum-}" ]; then
+  distributionSha256Result=false
+  if [ "$MVN_CMD" = mvnd.sh ]; then
+    echo "Checksum validation is not supported for maven-mvnd." >&2
+    echo "Please disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties." >&2
+    exit 1
+  elif command -v sha256sum >/dev/null; then
+    if echo "$distributionSha256Sum  $TMP_DOWNLOAD_DIR/$distributionUrlName" | sha256sum -c - >/dev/null 2>&1; then
+      distributionSha256Result=true
     fi
-  elif command -v shasum > /dev/null; then
+  elif command -v shasum >/dev/null; then
-    if echo "$wrapperSha256Sum  $wrapperJarPath" | shasum -a 256 -c > /dev/null 2>&1; then
+    if echo "$distributionSha256Sum  $TMP_DOWNLOAD_DIR/$distributionUrlName" | shasum -a 256 -c >/dev/null 2>&1; then
-      wrapperSha256Result=true
+      distributionSha256Result=true
     fi
   else
-    echo "Checksum validation was requested but neither 'sha256sum' or 'shasum' are available."
+    echo "Checksum validation was requested but neither 'sha256sum' or 'shasum' are available." >&2
-    echo "Please install either command, or disable validation by removing 'wrapperSha256Sum' from your maven-wrapper.properties."
+    echo "Please install either command, or disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties." >&2
     exit 1
   fi
-  if [ $wrapperSha256Result = false ]; then
+  if [ $distributionSha256Result = false ]; then
-    echo "Error: Failed to validate Maven wrapper SHA-256, your Maven wrapper might be compromised." >&2
+    echo "Error: Failed to validate Maven distribution SHA-256, your Maven distribution might be compromised." >&2
-    echo "Investigate or delete $wrapperJarPath to attempt a clean download." >&2
+    echo "If you updated your Maven version, you need to update the specified distributionSha256Sum property." >&2
-    echo "If you updated your Maven version, you need to update the specified wrapperSha256Sum property." >&2
     exit 1
   fi
 fi
 
-MAVEN_OPTS="$(concat_lines "$MAVEN_PROJECTBASEDIR/.mvn/jvm.config") $MAVEN_OPTS"
+# unzip and move
-
+if command -v unzip >/dev/null; then
-# For Cygwin, switch paths to Windows format before running java
+  unzip ${__MVNW_QUIET_UNZIP:+"$__MVNW_QUIET_UNZIP"} "$TMP_DOWNLOAD_DIR/$distributionUrlName" -d "$TMP_DOWNLOAD_DIR" || die "failed to unzip"
-if $cygwin; then
+else
-  [ -n "$JAVA_HOME" ] &&
+  tar xzf${__MVNW_QUIET_TAR:+"$__MVNW_QUIET_TAR"} "$TMP_DOWNLOAD_DIR/$distributionUrlName" -C "$TMP_DOWNLOAD_DIR" || die "failed to untar"
-    JAVA_HOME=$(cygpath --path --windows "$JAVA_HOME")
-  [ -n "$CLASSPATH" ] &&
-    CLASSPATH=$(cygpath --path --windows "$CLASSPATH")
-  [ -n "$MAVEN_PROJECTBASEDIR" ] &&
-    MAVEN_PROJECTBASEDIR=$(cygpath --path --windows "$MAVEN_PROJECTBASEDIR")
 fi
 
-# Provide a "standardized" way to retrieve the CLI args that will
+# Find the actual extracted directory name (handles snapshots where filename != directory name)
-# work with both Windows and non-Windows executions.
+actualDistributionDir=""
-MAVEN_CMD_LINE_ARGS="$MAVEN_CONFIG $*"
-export MAVEN_CMD_LINE_ARGS
 
-WRAPPER_LAUNCHER=org.apache.maven.wrapper.MavenWrapperMain
+# First try the expected directory name (for regular distributions)
+if [ -d "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain" ]; then
+  if [ -f "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain/bin/$MVN_CMD" ]; then
+    actualDistributionDir="$distributionUrlNameMain"
+  fi
+fi
 
-# shellcheck disable=SC2086 # safe args
+# If not found, search for any directory with the Maven executable (for snapshots)
-exec "$JAVACMD" \
+if [ -z "$actualDistributionDir" ]; then
-  $MAVEN_OPTS \
+  # enable globbing to iterate over items
-  $MAVEN_DEBUG_OPTS \
+  set +f
-  -classpath "$MAVEN_PROJECTBASEDIR/.mvn/wrapper/maven-wrapper.jar" \
+  for dir in "$TMP_DOWNLOAD_DIR"/*; do
-  "-Dmaven.multiModuleProjectDirectory=${MAVEN_PROJECTBASEDIR}" \
+    if [ -d "$dir" ]; then
-  ${WRAPPER_LAUNCHER} $MAVEN_CONFIG "$@"
+      if [ -f "$dir/bin/$MVN_CMD" ]; then
+        actualDistributionDir="$(basename "$dir")"
+        break
+      fi
+    fi
+  done
+  set -f
+fi
+
+if [ -z "$actualDistributionDir" ]; then
+  verbose "Contents of $TMP_DOWNLOAD_DIR:"
+  verbose "$(ls -la "$TMP_DOWNLOAD_DIR")"
+  die "Could not find Maven distribution directory in extracted archive"
+fi
+
+verbose "Found extracted Maven distribution directory: $actualDistributionDir"
+printf %s\\n "$distributionUrl" >"$TMP_DOWNLOAD_DIR/$actualDistributionDir/mvnw.url"
+mv -- "$TMP_DOWNLOAD_DIR/$actualDistributionDir" "$MAVEN_HOME" || [ -d "$MAVEN_HOME" ] || die "fail to move MAVEN_HOME"
+
+clean || :
+exec_maven "$@"

mvnw.cmd

@@ -1,3 +1,4 @@
+<# : batch portion
 @REM ----------------------------------------------------------------------------
 @REM Licensed to the Apache Software Foundation (ASF) under one
 @REM or more contributor license agreements.  See the NOTICE file
@@ -18,188 +19,171 @@
 @REM ----------------------------------------------------------------------------
 
 @REM ----------------------------------------------------------------------------
-@REM Apache Maven Wrapper startup batch script, version 3.2.0
+@REM Apache Maven Wrapper startup batch script, version 3.3.4
-@REM
-@REM Required ENV vars:
-@REM JAVA_HOME - location of a JDK home dir
 @REM
 @REM Optional ENV vars
-@REM MAVEN_BATCH_ECHO - set to 'on' to enable the echoing of the batch commands
+@REM   MVNW_REPOURL - repo url base for downloading maven distribution
-@REM MAVEN_BATCH_PAUSE - set to 'on' to wait for a keystroke before ending
+@REM   MVNW_USERNAME/MVNW_PASSWORD - user and password for downloading maven
-@REM MAVEN_OPTS - parameters passed to the Java VM when running Maven
+@REM   MVNW_VERBOSE - true: enable verbose log; others: silence the output
-@REM     e.g. to debug Maven itself, use
-@REM set MAVEN_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000
-@REM MAVEN_SKIP_RC - flag to disable loading of mavenrc files
 @REM ----------------------------------------------------------------------------
 
-@REM Begin all REM lines with '@' in case MAVEN_BATCH_ECHO is 'on'
+@IF "%__MVNW_ARG0_NAME__%"=="" (SET __MVNW_ARG0_NAME__=%~nx0)
-@echo off
+@SET __MVNW_CMD__=
-@REM set title of command window
+@SET __MVNW_ERROR__=
-title %0
+@SET __MVNW_PSMODULEP_SAVE=%PSModulePath%
-@REM enable echoing by setting MAVEN_BATCH_ECHO to 'on'
+@SET PSModulePath=
-@if "%MAVEN_BATCH_ECHO%" == "on"  echo %MAVEN_BATCH_ECHO%
+@FOR /F "usebackq tokens=1* delims==" %%A IN (`powershell -noprofile "& {$scriptDir='%~dp0'; $script='%__MVNW_ARG0_NAME__%'; icm -ScriptBlock ([Scriptblock]::Create((Get-Content -Raw '%~f0'))) -NoNewScope}"`) DO @(
-
+  IF "%%A"=="MVN_CMD" (set __MVNW_CMD__=%%B) ELSE IF "%%B"=="" (echo %%A) ELSE (echo %%A=%%B)
-@REM set %HOME% to equivalent of $HOME
-if "%HOME%" == "" (set "HOME=%HOMEDRIVE%%HOMEPATH%")
-
-@REM Execute a user defined script before this one
-if not "%MAVEN_SKIP_RC%" == "" goto skipRcPre
-@REM check for pre script, once with legacy .bat ending and once with .cmd ending
-if exist "%USERPROFILE%\mavenrc_pre.bat" call "%USERPROFILE%\mavenrc_pre.bat" %*
-if exist "%USERPROFILE%\mavenrc_pre.cmd" call "%USERPROFILE%\mavenrc_pre.cmd" %*
-:skipRcPre
-
-@setlocal
-
-set ERROR_CODE=0
-
-@REM To isolate internal variables from possible post scripts, we use another setlocal
-@setlocal
-
-@REM ==== START VALIDATION ====
-if not "%JAVA_HOME%" == "" goto OkJHome
-
-echo.
-echo Error: JAVA_HOME not found in your environment. >&2
-echo Please set the JAVA_HOME variable in your environment to match the >&2
-echo location of your Java installation. >&2
-echo.
-goto error
-
-:OkJHome
-if exist "%JAVA_HOME%\bin\java.exe" goto init
-
-echo.
-echo Error: JAVA_HOME is set to an invalid directory. >&2
-echo JAVA_HOME = "%JAVA_HOME%" >&2
-echo Please set the JAVA_HOME variable in your environment to match the >&2
-echo location of your Java installation. >&2
-echo.
-goto error
-
-@REM ==== END VALIDATION ====
-
-:init
-
-@REM Find the project base dir, i.e. the directory that contains the folder ".mvn".
-@REM Fallback to current working directory if not found.
-
-set MAVEN_PROJECTBASEDIR=%MAVEN_BASEDIR%
-IF NOT "%MAVEN_PROJECTBASEDIR%"=="" goto endDetectBaseDir
-
-set EXEC_DIR=%CD%
-set WDIR=%EXEC_DIR%
-:findBaseDir
-IF EXIST "%WDIR%"\.mvn goto baseDirFound
-cd ..
-IF "%WDIR%"=="%CD%" goto baseDirNotFound
-set WDIR=%CD%
-goto findBaseDir
-
-:baseDirFound
-set MAVEN_PROJECTBASEDIR=%WDIR%
-cd "%EXEC_DIR%"
-goto endDetectBaseDir
-
-:baseDirNotFound
-set MAVEN_PROJECTBASEDIR=%EXEC_DIR%
-cd "%EXEC_DIR%"
-
-:endDetectBaseDir
-
-IF NOT EXIST "%MAVEN_PROJECTBASEDIR%\.mvn\jvm.config" goto endReadAdditionalConfig
-
-@setlocal EnableExtensions EnableDelayedExpansion
-for /F "usebackq delims=" %%a in ("%MAVEN_PROJECTBASEDIR%\.mvn\jvm.config") do set JVM_CONFIG_MAVEN_PROPS=!JVM_CONFIG_MAVEN_PROPS! %%a
-@endlocal & set JVM_CONFIG_MAVEN_PROPS=%JVM_CONFIG_MAVEN_PROPS%
-
-:endReadAdditionalConfig
-
-SET MAVEN_JAVA_EXE="%JAVA_HOME%\bin\java.exe"
-set WRAPPER_JAR="%MAVEN_PROJECTBASEDIR%\.mvn\wrapper\maven-wrapper.jar"
-set WRAPPER_LAUNCHER=org.apache.maven.wrapper.MavenWrapperMain
-
-set WRAPPER_URL="https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.2.0/maven-wrapper-3.2.0.jar"
-
-FOR /F "usebackq tokens=1,2 delims==" %%A IN ("%MAVEN_PROJECTBASEDIR%\.mvn\wrapper\maven-wrapper.properties") DO (
-    IF "%%A"=="wrapperUrl" SET WRAPPER_URL=%%B
 )
+@SET PSModulePath=%__MVNW_PSMODULEP_SAVE%
+@SET __MVNW_PSMODULEP_SAVE=
+@SET __MVNW_ARG0_NAME__=
+@SET MVNW_USERNAME=
+@SET MVNW_PASSWORD=
+@IF NOT "%__MVNW_CMD__%"=="" ("%__MVNW_CMD__%" %*)
+@echo Cannot start maven from wrapper >&2 && exit /b 1
+@GOTO :EOF
+: end batch / begin powershell #>
 
-@REM Extension to allow automatically downloading the maven-wrapper.jar from Maven-central
+$ErrorActionPreference = "Stop"
-@REM This allows using the maven wrapper in projects that prohibit checking in binary data.
+if ($env:MVNW_VERBOSE -eq "true") {
-if exist %WRAPPER_JAR% (
+  $VerbosePreference = "Continue"
-    if "%MVNW_VERBOSE%" == "true" (
+}
-        echo Found %WRAPPER_JAR%
-    )
-) else (
-    if not "%MVNW_REPOURL%" == "" (
-        SET WRAPPER_URL="%MVNW_REPOURL%/org/apache/maven/wrapper/maven-wrapper/3.2.0/maven-wrapper-3.2.0.jar"
-    )
-    if "%MVNW_VERBOSE%" == "true" (
-        echo Couldn't find %WRAPPER_JAR%, downloading it ...
-        echo Downloading from: %WRAPPER_URL%
-    )
 
-    powershell -Command "&{"^
+# calculate distributionUrl, requires .mvn/wrapper/maven-wrapper.properties
-		"$webclient = new-object System.Net.WebClient;"^
+$distributionUrl = (Get-Content -Raw "$scriptDir/.mvn/wrapper/maven-wrapper.properties" | ConvertFrom-StringData).distributionUrl
-		"if (-not ([string]::IsNullOrEmpty('%MVNW_USERNAME%') -and [string]::IsNullOrEmpty('%MVNW_PASSWORD%'))) {"^
+if (!$distributionUrl) {
-		"$webclient.Credentials = new-object System.Net.NetworkCredential('%MVNW_USERNAME%', '%MVNW_PASSWORD%');"^
+  Write-Error "cannot read distributionUrl property in $scriptDir/.mvn/wrapper/maven-wrapper.properties"
-		"}"^
+}
-		"[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; $webclient.DownloadFile('%WRAPPER_URL%', '%WRAPPER_JAR%')"^
-		"}"
-    if "%MVNW_VERBOSE%" == "true" (
-        echo Finished downloading %WRAPPER_JAR%
-    )
-)
-@REM End of extension
 
-@REM If specified, validate the SHA-256 sum of the Maven wrapper jar file
+switch -wildcard -casesensitive ( $($distributionUrl -replace '^.*/','') ) {
-SET WRAPPER_SHA_256_SUM=""
+  "maven-mvnd-*" {
-FOR /F "usebackq tokens=1,2 delims==" %%A IN ("%MAVEN_PROJECTBASEDIR%\.mvn\wrapper\maven-wrapper.properties") DO (
+    $USE_MVND = $true
-    IF "%%A"=="wrapperSha256Sum" SET WRAPPER_SHA_256_SUM=%%B
+    $distributionUrl = $distributionUrl -replace '-bin\.[^.]*$',"-windows-amd64.zip"
-)
+    $MVN_CMD = "mvnd.cmd"
-IF NOT %WRAPPER_SHA_256_SUM%=="" (
+    break
-    powershell -Command "&{"^
+  }
-       "$hash = (Get-FileHash \"%WRAPPER_JAR%\" -Algorithm SHA256).Hash.ToLower();"^
+  default {
-       "If('%WRAPPER_SHA_256_SUM%' -ne $hash){"^
+    $USE_MVND = $false
-       "  Write-Output 'Error: Failed to validate Maven wrapper SHA-256, your Maven wrapper might be compromised.';"^
+    $MVN_CMD = $script -replace '^mvnw','mvn'
-       "  Write-Output 'Investigate or delete %WRAPPER_JAR% to attempt a clean download.';"^
+    break
-       "  Write-Output 'If you updated your Maven version, you need to update the specified wrapperSha256Sum property.';"^
+  }
-       "  exit 1;"^
+}
-       "}"^
-       "}"
-    if ERRORLEVEL 1 goto error
-)
 
-@REM Provide a "standardized" way to retrieve the CLI args that will
+# apply MVNW_REPOURL and calculate MAVEN_HOME
-@REM work with both Windows and non-Windows executions.
+# maven home pattern: ~/.m2/wrapper/dists/{apache-maven-<version>,maven-mvnd-<version>-<platform>}/<hash>
-set MAVEN_CMD_LINE_ARGS=%*
+if ($env:MVNW_REPOURL) {
+  $MVNW_REPO_PATTERN = if ($USE_MVND -eq $False) { "/org/apache/maven/" } else { "/maven/mvnd/" }
+  $distributionUrl = "$env:MVNW_REPOURL$MVNW_REPO_PATTERN$($distributionUrl -replace "^.*$MVNW_REPO_PATTERN",'')"
+}
+$distributionUrlName = $distributionUrl -replace '^.*/',''
+$distributionUrlNameMain = $distributionUrlName -replace '\.[^.]*$','' -replace '-bin$',''
 
-%MAVEN_JAVA_EXE% ^
+$MAVEN_M2_PATH = "$HOME/.m2"
-  %JVM_CONFIG_MAVEN_PROPS% ^
+if ($env:MAVEN_USER_HOME) {
-  %MAVEN_OPTS% ^
+  $MAVEN_M2_PATH = "$env:MAVEN_USER_HOME"
-  %MAVEN_DEBUG_OPTS% ^
+}
-  -classpath %WRAPPER_JAR% ^
-  "-Dmaven.multiModuleProjectDirectory=%MAVEN_PROJECTBASEDIR%" ^
-  %WRAPPER_LAUNCHER% %MAVEN_CONFIG% %*
-if ERRORLEVEL 1 goto error
-goto end
 
-:error
+if (-not (Test-Path -Path $MAVEN_M2_PATH)) {
-set ERROR_CODE=1
+    New-Item -Path $MAVEN_M2_PATH -ItemType Directory | Out-Null
+}
 
-:end
+$MAVEN_WRAPPER_DISTS = $null
-@endlocal & set ERROR_CODE=%ERROR_CODE%
+if ((Get-Item $MAVEN_M2_PATH).Target[0] -eq $null) {
+  $MAVEN_WRAPPER_DISTS = "$MAVEN_M2_PATH/wrapper/dists"
+} else {
+  $MAVEN_WRAPPER_DISTS = (Get-Item $MAVEN_M2_PATH).Target[0] + "/wrapper/dists"
+}
 
-if not "%MAVEN_SKIP_RC%"=="" goto skipRcPost
+$MAVEN_HOME_PARENT = "$MAVEN_WRAPPER_DISTS/$distributionUrlNameMain"
-@REM check for post script, once with legacy .bat ending and once with .cmd ending
+$MAVEN_HOME_NAME = ([System.Security.Cryptography.SHA256]::Create().ComputeHash([byte[]][char[]]$distributionUrl) | ForEach-Object {$_.ToString("x2")}) -join ''
-if exist "%USERPROFILE%\mavenrc_post.bat" call "%USERPROFILE%\mavenrc_post.bat"
+$MAVEN_HOME = "$MAVEN_HOME_PARENT/$MAVEN_HOME_NAME"
-if exist "%USERPROFILE%\mavenrc_post.cmd" call "%USERPROFILE%\mavenrc_post.cmd"
-:skipRcPost
 
-@REM pause the script if MAVEN_BATCH_PAUSE is set to 'on'
+if (Test-Path -Path "$MAVEN_HOME" -PathType Container) {
-if "%MAVEN_BATCH_PAUSE%"=="on" pause
+  Write-Verbose "found existing MAVEN_HOME at $MAVEN_HOME"
+  Write-Output "MVN_CMD=$MAVEN_HOME/bin/$MVN_CMD"
+  exit $?
+}
 
-if "%MAVEN_TERMINATE_CMD%"=="on" exit %ERROR_CODE%
+if (! $distributionUrlNameMain -or ($distributionUrlName -eq $distributionUrlNameMain)) {
+  Write-Error "distributionUrl is not valid, must end with *-bin.zip, but found $distributionUrl"
+}
 
-cmd /C exit /B %ERROR_CODE%
+# prepare tmp dir
+$TMP_DOWNLOAD_DIR_HOLDER = New-TemporaryFile
+$TMP_DOWNLOAD_DIR = New-Item -Itemtype Directory -Path "$TMP_DOWNLOAD_DIR_HOLDER.dir"
+$TMP_DOWNLOAD_DIR_HOLDER.Delete() | Out-Null
+trap {
+  if ($TMP_DOWNLOAD_DIR.Exists) {
+    try { Remove-Item $TMP_DOWNLOAD_DIR -Recurse -Force | Out-Null }
+    catch { Write-Warning "Cannot remove $TMP_DOWNLOAD_DIR" }
+  }
+}
+
+New-Item -Itemtype Directory -Path "$MAVEN_HOME_PARENT" -Force | Out-Null
+
+# Download and Install Apache Maven
+Write-Verbose "Couldn't find MAVEN_HOME, downloading and installing it ..."
+Write-Verbose "Downloading from: $distributionUrl"
+Write-Verbose "Downloading to: $TMP_DOWNLOAD_DIR/$distributionUrlName"
+
+$webclient = New-Object System.Net.WebClient
+if ($env:MVNW_USERNAME -and $env:MVNW_PASSWORD) {
+  $webclient.Credentials = New-Object System.Net.NetworkCredential($env:MVNW_USERNAME, $env:MVNW_PASSWORD)
+}
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+$webclient.DownloadFile($distributionUrl, "$TMP_DOWNLOAD_DIR/$distributionUrlName") | Out-Null
+
+# If specified, validate the SHA-256 sum of the Maven distribution zip file
+$distributionSha256Sum = (Get-Content -Raw "$scriptDir/.mvn/wrapper/maven-wrapper.properties" | ConvertFrom-StringData).distributionSha256Sum
+if ($distributionSha256Sum) {
+  if ($USE_MVND) {
+    Write-Error "Checksum validation is not supported for maven-mvnd. `nPlease disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties."
+  }
+  Import-Module $PSHOME\Modules\Microsoft.PowerShell.Utility -Function Get-FileHash
+  if ((Get-FileHash "$TMP_DOWNLOAD_DIR/$distributionUrlName" -Algorithm SHA256).Hash.ToLower() -ne $distributionSha256Sum) {
+    Write-Error "Error: Failed to validate Maven distribution SHA-256, your Maven distribution might be compromised. If you updated your Maven version, you need to update the specified distributionSha256Sum property."
+  }
+}
+
+# unzip and move
+Expand-Archive "$TMP_DOWNLOAD_DIR/$distributionUrlName" -DestinationPath "$TMP_DOWNLOAD_DIR" | Out-Null
+
+# Find the actual extracted directory name (handles snapshots where filename != directory name)
+$actualDistributionDir = ""
+
+# First try the expected directory name (for regular distributions)
+$expectedPath = Join-Path "$TMP_DOWNLOAD_DIR" "$distributionUrlNameMain"
+$expectedMvnPath = Join-Path "$expectedPath" "bin/$MVN_CMD"
+if ((Test-Path -Path $expectedPath -PathType Container) -and (Test-Path -Path $expectedMvnPath -PathType Leaf)) {
+  $actualDistributionDir = $distributionUrlNameMain
+}
+
+# If not found, search for any directory with the Maven executable (for snapshots)
+if (!$actualDistributionDir) {
+  Get-ChildItem -Path "$TMP_DOWNLOAD_DIR" -Directory | ForEach-Object {
+    $testPath = Join-Path $_.FullName "bin/$MVN_CMD"
+    if (Test-Path -Path $testPath -PathType Leaf) {
+      $actualDistributionDir = $_.Name
+    }
+  }
+}
+
+if (!$actualDistributionDir) {
+  Write-Error "Could not find Maven distribution directory in extracted archive"
+}
+
+Write-Verbose "Found extracted Maven distribution directory: $actualDistributionDir"
+Rename-Item -Path "$TMP_DOWNLOAD_DIR/$actualDistributionDir" -NewName $MAVEN_HOME_NAME | Out-Null
+try {
+  Move-Item -Path "$TMP_DOWNLOAD_DIR/$MAVEN_HOME_NAME" -Destination $MAVEN_HOME_PARENT | Out-Null
+} catch {
+  if (! (Test-Path -Path "$MAVEN_HOME" -PathType Container)) {
+    Write-Error "fail to move MAVEN_HOME"
+  }
+} finally {
+  try { Remove-Item $TMP_DOWNLOAD_DIR -Recurse -Force | Out-Null }
+  catch { Write-Warning "Cannot remove $TMP_DOWNLOAD_DIR" }
+}
+
+Write-Output "MVN_CMD=$MAVEN_HOME/bin/$MVN_CMD"

pom.xml

@@ -12,11 +12,12 @@
     <packaging>jar</packaging>
 
     <properties>
-        <main.class>me.bobert.netneutrality.NetNeutrality</main.class>
+        <main.class>me.bobert.netneutrality.App</main.class>
-        <java.version>17</java.version>
+        <java.version>25</java.version>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-        <maven.compiler.source>17</maven.compiler.source>
+        <maven.compiler.source>25</maven.compiler.source>
-        <maven.compiler.target>17</maven.compiler.target>
+        <maven.compiler.target>25</maven.compiler.target>
+        <mockito.version>5.23.0</mockito.version>
     </properties>
 
     <build>
@@ -28,52 +29,95 @@
         </resources>
 
         <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <version>3.5.5</version>
+                <configuration>
+                    <argLine>
+                        -javaagent:"${settings.localRepository}/org/mockito/mockito-core/${mockito.version}/mockito-core-${mockito.version}.jar"
+                    </argLine>
+                </configuration>
+            </plugin>
             <plugin>
                 <groupId>org.flywaydb</groupId>
                 <artifactId>flyway-maven-plugin</artifactId>
-                <version>10.17.0</version>
+                <version>11.20.3</version>
                 <configuration>
-                    <url>jdbc:mysql://localhost:3306/netneutrality</url>
+                    <url>${env.FLYWAY_URL}</url>
-                    <user>root</user>
+                    <user>${env.FLYWAY_USER}</user>
-                    <password></password>
+                    <password>${env.FLYWAY_PASSWORD}</password>
                 </configuration>
             </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-resources-plugin</artifactId>
-                <version>3.3.1</version>
+                <version>3.5.0</version>
                 <configuration>
                     <propertiesEncoding>UTF-8</propertiesEncoding>
                 </configuration>
             </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-assembly-plugin</artifactId>
+                <artifactId>maven-jar-plugin</artifactId>
-                <version>3.7.1</version>
+                <version>3.5.0</version>
                 <configuration>
                     <archive>
-                        <manifestEntries>
-                            <Multi-Release>true</Multi-Release>
-                        </manifestEntries>
                         <manifest>
-                            <addClasspath>true</addClasspath>
                             <mainClass>${main.class}</mainClass>
                         </manifest>
                     </archive>
-                    <descriptorRefs>
-                        <descriptorRef>jar-with-dependencies</descriptorRef>
-                    </descriptorRefs>
-                    <finalName>netneutrality</finalName>
                 </configuration>
+            </plugin>
+
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-shade-plugin</artifactId>
+                <version>3.6.2</version>
                 <executions>
                     <execution>
-                        <id>make-assembly</id> <!-- this is used for inheritance merges -->
+                        <phase>package</phase>
-                        <phase>package</phase> <!-- bind to the packaging phase -->
                         <goals>
-                            <goal>single</goal>
+                            <goal>shade</goal>
+                        </goals>
+                        <configuration>
+                            <finalName>netneutrality</finalName>
+                            <transformers>
+                                <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+                                    <mainClass>${main.class}</mainClass>
+                                </transformer>
+                                <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
+                                <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+                                    <manifestEntries>
+                                        <Multi-Release>true</Multi-Release>
+                                    </manifestEntries>
+                                </transformer>
+                            </transformers>
+                            <createDependencyReducedPom>false</createDependencyReducedPom>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-checkstyle-plugin</artifactId>
+                <version>3.6.0</version>
+                <executions>
+                    <execution>
+                        <id>checkstyle</id>
+                        <phase>test</phase>
+                        <goals>
+                            <goal>check</goal>
                         </goals>
                     </execution>
                 </executions>
+                <configuration>
+                    <configLocation>checkstyle.xml</configLocation>
+                    <failOnViolation>true</failOnViolation>
+                    <linkXRef>false</linkXRef>
+                    <outputFile>target/checkstyle-result.xml</outputFile>
+                    <outputFormat>xml</outputFormat>
+                </configuration>
             </plugin>
         </plugins>
     </build>
@@ -100,71 +144,98 @@
         <dependency>
             <groupId>net.dv8tion</groupId>
             <artifactId>JDA</artifactId>
-            <version>5.1.2</version>
+            <version>6.4.1</version>
         </dependency>
         <dependency>
             <groupId>dev.arbjerg</groupId>
             <artifactId>lavaplayer</artifactId>
-            <version>2.2.2</version>
+            <version>2.2.7</version>
         </dependency>
         <dependency>
             <groupId>dev.lavalink.youtube</groupId>
             <artifactId>v2</artifactId>
-            <version>1.11.5</version>
+            <version>1.18.2</version>
+        </dependency>
+        <dependency>
+            <groupId>club.minnced</groupId>
+            <artifactId>jdave-api</artifactId>
+            <version>0.1.8</version>
+        </dependency>
+        <dependency>
+            <groupId>club.minnced</groupId>
+            <artifactId>jdave-native-linux-x86-64</artifactId>
+            <version>0.1.8</version>
+        </dependency>
+        <dependency>
+            <groupId>club.minnced</groupId>
+            <artifactId>jdave-native-win-x86-64</artifactId>
+            <version>0.1.8</version>
+        </dependency>
+        <dependency>
+            <groupId>club.minnced</groupId>
+            <artifactId>jdave-native-darwin</artifactId>
+            <version>0.1.8</version>
         </dependency>
 
         <dependency>
             <groupId>com.squareup.okhttp3</groupId>
-            <artifactId>okhttp</artifactId>
+            <artifactId>okhttp-jvm</artifactId>
-            <version>4.12.0</version>
+            <version>5.3.2</version>
         </dependency>
 
         <dependency>
             <groupId>org.hibernate.orm</groupId>
             <artifactId>hibernate-core</artifactId>
-            <version>6.5.2.Final</version>
+            <version>7.1.9.Final</version>
         </dependency>
         <dependency>
             <groupId>org.hibernate.orm</groupId>
             <artifactId>hibernate-hikaricp</artifactId>
-            <version>6.5.2.Final</version>
+            <version>7.1.9.Final</version>
         </dependency>
         <dependency>
             <groupId>com.mysql</groupId>
             <artifactId>mysql-connector-j</artifactId>
-            <version>9.0.0</version>
+            <version>9.7.0</version>
         </dependency>
         <dependency>
             <groupId>org.flywaydb</groupId>
             <artifactId>flyway-core</artifactId>
-            <version>10.17.0</version>
+            <version>11.20.3</version>
         </dependency>
         <dependency>
             <groupId>org.flywaydb</groupId>
             <artifactId>flyway-mysql</artifactId>
-            <version>10.17.0</version>
+            <version>11.20.3</version>
+            <scope>runtime</scope>
         </dependency>
 
         <dependency>
             <groupId>io.sentry</groupId>
             <artifactId>sentry</artifactId>
-            <version>7.12.1</version>
+            <version>8.41.0</version>
         </dependency>
         <dependency>
             <groupId>org.gitlab4j</groupId>
             <artifactId>gitlab4j-api</artifactId>
-            <version>6.0.0-rc.5</version>
+            <version>6.2.0</version>
         </dependency>
+
         <dependency>
             <groupId>net.fellbaum</groupId>
             <artifactId>jemoji</artifactId>
-            <version>1.7.0</version>
+            <version>1.7.6</version>
         </dependency>
 
         <dependency>
             <groupId>org.json</groupId>
             <artifactId>json</artifactId>
-            <version>20240303</version>
+            <version>20250517</version>
+        </dependency>
+        <dependency>
+            <groupId>com.google.code.gson</groupId>
+            <artifactId>gson</artifactId>
+            <version>2.14.0</version>
         </dependency>
 
         <dependency>
@@ -176,41 +247,48 @@
         <dependency>
             <groupId>org.apache.logging.log4j</groupId>
             <artifactId>log4j-api</artifactId>
-            <version>2.23.1</version>
+            <version>2.26.0</version>
         </dependency>
         <dependency>
             <groupId>org.apache.logging.log4j</groupId>
             <artifactId>log4j-core</artifactId>
-            <version>2.23.1</version>
+            <version>2.26.0</version>
         </dependency>
         <dependency>
             <groupId>org.apache.logging.log4j</groupId>
             <artifactId>log4j-slf4j2-impl</artifactId>
-            <version>2.23.1</version>
+            <version>2.26.0</version>
         </dependency>
 
         <dependency>
             <groupId>org.apache.commons</groupId>
             <artifactId>commons-lang3</artifactId>
-            <version>3.15.0</version>
+            <version>3.19.0</version>
-        </dependency>
-        <dependency>
-            <groupId>commons-codec</groupId>
-            <artifactId>commons-codec</artifactId>
-            <version>1.17.0</version>
         </dependency>
         <dependency>
             <groupId>commons-io</groupId>
             <artifactId>commons-io</artifactId>
-            <version>2.16.1</version>
+            <version>2.21.0</version>
         </dependency>
 
         <dependency>
             <groupId>org.junit.jupiter</groupId>
             <artifactId>junit-jupiter</artifactId>
-            <version>5.11.0</version>
+            <version>6.0.3</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <version>${mockito.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-junit-jupiter</artifactId>
+            <version>${mockito.version}</version>
+            <scope>test</scope>
         </dependency>
-
     </dependencies>
 
 </project>

renovate.json

@@ -1,6 +1,63 @@
 {
   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
   "extends": [
-    "renovate/renovate-config"
+    "local>renovate/renovate-config",
+    "group:monorepos",
+    "group:flyway"
+  ],
+  "packageRules": [
+    {
+      "matchPackageNames": [
+        "mariadb"
+      ],
+      "automerge": false,
+      "dependencyDashboardApproval": true
+    },
+    {
+      "matchManagers": ["maven"],
+      "extends": ["schedule:monthly"]
+    },
+    {
+      "groupName": "maven plugins",
+      "matchManagers": ["maven"],
+      "matchDepTypes": ["plugin"],
+      "extends": ["schedule:weekly"]
+    },
+    {
+      "groupName": "hibernate orm",
+      "matchPackageNames": [
+        "org.hibernate.orm:**"
+      ],
+      "extends": ["schedule:monthly"]
+    },
+    {
+      "groupName": "apache commons",
+      "matchPackageNames": [
+        "commons-**",
+        "org.apache.commons:**"
+      ],
+      "extends": ["schedule:monthly"]
+    },
+    {
+      "matchManagers": ["maven"],
+      "matchDepTypes": ["dependency", "parentPom"],
+      "matchPackageNames": [
+        "net.dv8tion:JDA",
+        "dev.arbjerg:lavaplayer",
+        "dev.lavalink.youtube:**",
+        "club.minnced:jdave-*"
+      ],
+      "schedule": ["at any time"]
+    },
+    {
+      "groupName": "github actions (minor/patch)",
+      "matchManagers": ["github-actions"],
+      "matchUpdateTypes": ["minor", "patch", "digest"]
+    },
+    {
+      "groupName": "github actions (major)",
+      "matchManagers": ["github-actions"],
+      "matchUpdateTypes": ["major"]
+    }
   ]
 }

src/main/java/me/bobert/netneutrality/App.java

@@ -0,0 +1,229 @@
+package me.bobert.netneutrality;
+
+/*
+ * Copyright (c) anthorob
+ *
+ * https://discord.gg/qUa6zNFZsd
+ */
+
+import club.minnced.discord.jdave.interop.JDaveSessionFactory;
+import io.sentry.Sentry;
+import me.bobert.netneutrality.bootstrap.ApplicationContext;
+import me.bobert.netneutrality.bootstrap.Lifecycle;
+import me.bobert.netneutrality.bootstrap.BotState;
+import me.bobert.netneutrality.core.LogHandler;
+import me.bobert.netneutrality.core.command.CommandManager;
+import me.bobert.netneutrality.db.SessionManager;
+import me.bobert.netneutrality.core.tasks.TaskManagerImpl;
+import me.bobert.netneutrality.core.scheduled.ScheduledTaskManager;
+import me.bobert.netneutrality.core.thread.ThreadManager;
+import me.bobert.netneutrality.db.service.GuildServiceProviderImpl;
+import me.bobert.netneutrality.music.MusicService;
+import me.bobert.netneutrality.core.command.CommandRegistry;
+import me.bobert.netneutrality.core.tasks.TaskManager;
+import me.bobert.netneutrality.hooks.EventsHandler;
+import me.bobert.netneutrality.http.server.WebApi;
+import me.bobert.netneutrality.music.MusicServiceImpl;
+import me.bobert.netneutrality.core.thread.ExecutorProvider;
+import me.bobert.netneutrality.utils.SettingsProvider;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+import me.bobert.netneutrality.utils.ChannelMessagePurger;
+import me.bobert.netneutrality.db.JpaUtils;
+import me.bobert.netneutrality.utils.Settings;
+import me.bobert.netneutrality.http.WebModule;
+import net.dv8tion.jda.api.JDA;
+import net.dv8tion.jda.api.JDABuilder;
+import net.dv8tion.jda.api.audio.AudioModuleConfig;
+import net.dv8tion.jda.api.entities.Activity;
+import net.dv8tion.jda.api.exceptions.InvalidTokenException;
+import net.dv8tion.jda.api.requests.GatewayIntent;
+import org.apache.logging.log4j.Level;
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+import org.apache.logging.log4j.core.config.Configurator;
+
+public class App {
+    private static final Logger logger = LogManager.getLogger(App.class);
+    private static App instance;
+    private final Settings settings;
+    private JDA jda;
+    private final ApplicationContext context = new ApplicationContext();
+
+    static void main() {
+        Settings settings = new Settings();
+        String version = settings.getMavenVersion();
+        WebModule.setDefaultVersion(version);
+        logger.info("Starting App v{}", version);
+
+        String env = settings.get("NETNEUTRALITY_BOT_ENV", "dev");
+        String sentryDsn = settings.get("NETNEUTRALITY_SENTRY_DSN");
+        if (sentryDsn != null) {
+            logger.info("Found Sentry DSN in config, setting up the SDK..");
+
+            Sentry.init(options -> {
+                options.setDsn(sentryDsn);
+                options.setEnvironment(env);
+                options.setTracesSampleRate(1.0);
+                options.setDebug(false);
+                options.setRelease(version);
+            });
+        }
+
+        if ("dev".equals(env)) {
+            Configurator.setLevel("net.dv8tion.jda", Level.DEBUG);
+            Configurator.setLevel("dev.lavalink.youtube", Level.DEBUG);
+            Configurator.setLevel("com.sedmelluq.discord", Level.DEBUG);
+        }
+
+        instance = new App(settings);
+    }
+
+    public App(Settings settings) {
+        this.settings = settings;
+        startup();
+    }
+
+    private void startup() {
+        String token = settings.get("NETNEUTRALITY_BOT_TOKEN");
+        if (token == null) {
+            throw new RuntimeException("No bot token provided, exiting.");
+        }
+
+        buildContext();
+
+        try {
+            context.start();
+        } catch (Exception e) {
+            LogHandler.log(e);
+            System.exit(1);
+        }
+
+        Runtime.getRuntime().addShutdownHook(new Thread(this::shutdown));
+    }
+
+    /**
+     * Registers domain services and remaining startup/shutdown adapters with the
+     * {@link ApplicationContext}. Ascending {@link Lifecycle#priority()} drives startup order; the
+     * context stops components in the exact reverse order.
+     */
+    private void buildContext() {
+        // Config first so SettingsProvider is resolvable for constructor injection.
+        context.register((SettingsProvider) settings);
+
+        // Allow ApplicationContext itself to be injected into components that need it.
+        context.register(context);
+
+        // Persistence: build the SessionFactory + run migrations; released last on shutdown.
+        // SessionManager binds itself into JpaUtils for repository access.
+        context.register(new SessionManager(settings));
+
+        // Executors: no explicit start today; shut down after music players are disconnected.
+        ExecutorProvider executors = context.register(new ThreadManager());
+        ChannelMessagePurger.bind(executors);
+
+        // Scheduled tasks (priority 55): discovers and schedules all ScheduledTask implementations
+        // on start; cancelled early on shutdown, before executors.
+        context.register(new ScheduledTaskManager(executors, context));
+
+        // Command registry (priority 30).
+        CommandRegistry commands = context.register(new CommandManager(context));
+
+        // Task registry (priority 30).
+        TaskManager tasks = context.register(new TaskManagerImpl(context));
+
+        // Per-guild service cache (not a Lifecycle component).
+        GuildServiceProvider guildServices = context.register(new GuildServiceProviderImpl());
+        LogHandler.bind(guildServices);
+        JpaUtils.bindGuildServiceLookup(guildServices::get);
+
+        // Music sources (priority 40): initialise the shared player manager; disconnect on shutdown.
+        MusicService music = context.register(new MusicServiceImpl(settings, guildServices, tasks));
+        BotState.bind(guildServices, music);
+
+        // JDA gateway; disconnected on shutdown.
+        context.register(lifecycle(60, this::initJDA, this::disconnect));
+
+        // Register slash commands, attach the event handler and set the presence once JDA is ready.
+        context.register(lifecycle(65, () -> {
+            commands.registerSlashCommands(jda);
+            jda.addEventListener(new EventsHandler(settings, guildServices, commands, tasks));
+            jda.getPresence().setActivity(Activity.watching("you"));
+        }, () -> { }));
+
+        // Web API (priority 70) — Lifecycle with graceful stop.
+        context.register(new WebApi(settings, guildServices, this::getJDA, this::shutdown));
+    }
+
+    private static Lifecycle lifecycle(int priority, ThrowingRunnable start, Runnable stop) {
+        return new Lifecycle() {
+            @Override
+            public void start() throws Exception {
+                start.run();
+            }
+
+            @Override
+            public void stop() {
+                stop.run();
+            }
+
+            @Override
+            public int priority() {
+                return priority;
+            }
+        };
+    }
+
+    @FunctionalInterface
+    private interface ThrowingRunnable {
+        void run() throws Exception;
+    }
+
+    public static App getInstance() {
+        return instance;
+    }
+
+    public void initJDA() {
+        String token = settings.get("NETNEUTRALITY_BOT_TOKEN");
+        if (token == null) {
+            SessionManager sessions = context.get(SessionManager.class);
+            if (sessions != null) {
+                sessions.stop();
+            }
+            throw new RuntimeException("No bot token provided, exiting.");
+        }
+
+        try {
+            jda = JDABuilder
+                .createDefault(token)
+                .enableIntents(
+                    GatewayIntent.GUILD_MEMBERS,
+                    GatewayIntent.GUILD_MESSAGE_REACTIONS,
+                    GatewayIntent.GUILD_VOICE_STATES,
+                    GatewayIntent.MESSAGE_CONTENT)
+                .setAudioModuleConfig(
+                    new AudioModuleConfig().withDaveSessionFactory(new JDaveSessionFactory()))
+                .setActivity(Activity.watching("me load..."))
+                .build();
+            jda.awaitReady();
+        } catch (InvalidTokenException | IllegalArgumentException | InterruptedException e) {
+            LogHandler.log(e);
+            System.exit(1);
+        }
+    }
+
+    public void shutdown() {
+        logger.info("[Net Neutrality] Shutting down...");
+        context.stop();
+        logger.info("[Net Neutrality] Shutdown complete");
+    }
+
+    public JDA getJDA() {
+        return jda;
+    }
+
+    private void disconnect() {
+        if (jda != null) {
+            jda.shutdown();
+        }
+    }
+}

src/main/java/me/bobert/netneutrality/NetNeutrality.java

@@ -1,126 +0,0 @@
-package me.bobert.netneutrality;
-
-/*
- * Copyright (c) anthorob
- *
- * https://discord.gg/qUa6zNFZsd
- */
-
-import io.sentry.Sentry;
-import me.bobert.netneutrality.core.LogHandler;
-import me.bobert.netneutrality.core.command.CommandManager;
-import me.bobert.netneutrality.core.db.SessionManager;
-import me.bobert.netneutrality.core.tasks.TaskManager;
-import me.bobert.netneutrality.core.thread.ThreadManager;
-import me.bobert.netneutrality.hooks.EventsHandler;
-import me.bobert.netneutrality.http.server.WebApi;
-import me.bobert.netneutrality.music.MusicManager;
-import me.bobert.netneutrality.thread.ShutdownThread;
-import me.bobert.netneutrality.utils.Settings;
-import net.dv8tion.jda.api.JDA;
-import net.dv8tion.jda.api.JDABuilder;
-import net.dv8tion.jda.api.entities.Activity;
-import net.dv8tion.jda.api.exceptions.InvalidTokenException;
-import net.dv8tion.jda.api.requests.GatewayIntent;
-import org.apache.logging.log4j.Level;
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
-import org.apache.logging.log4j.core.config.Configurator;
-
-public class NetNeutrality {
-    private static final Logger logger = LogManager.getLogger(NetNeutrality.class);
-    public static final String VERSION = Settings.getVersion();
-    private static NetNeutrality instance;
-    private static JDA jda;
-
-    public static void main(String[] args) {
-        System.out.println("Starting NetNeutrality v" + VERSION);
-
-        String env = Settings.getInstance().get("NETNEUTRALITY_BOT_ENV", "dev");
-        String sentryDsn = Settings.getInstance().get("NETNEUTRALITY_SENTRY_DSN");
-        if (sentryDsn != null) {
-            logger.info("Found Sentry DSN in config, setting up the SDK..");
-
-            Sentry.init(options -> {
-                options.setDsn(sentryDsn);
-                options.setEnvironment(env);
-                options.setTracesSampleRate(1.0);
-                options.setDebug(false);
-                options.setRelease(VERSION);
-            });
-        }
-
-        if ("dev".equals(env)) {
-            Configurator.setLevel("net.dv8tion.jda", Level.DEBUG);
-        }
-
-        instance = new NetNeutrality();
-    }
-
-    public NetNeutrality() {
-        startup();
-    }
-
-    private void startup() {
-        String token = Settings.getInstance().get("NETNEUTRALITY_BOT_TOKEN");
-        if (token == null) {
-            throw new RuntimeException("No bot token provided, exiting.");
-        }
-
-        // DatabaseMigration.migrate();
-        SessionManager.getSessionFactory();
-        CommandManager.init();
-        MusicManager.initPlayerManager();
-        TaskManager.getInstance().init();
-        initJDA();
-        CommandManager.registerSlashCommands(jda);
-        jda.addEventListener(new EventsHandler());
-        new WebApi(Integer.parseInt(Settings.getInstance().get("NETNEUTRALITY_API_PORT", "9000")));
-        jda.getPresence().setActivity(Activity.watching("you"));
-
-        Runtime.getRuntime().addShutdownHook(new ShutdownThread(this));
-    }
-
-    public static NetNeutrality getInstance() {
-        return instance;
-    }
-
-    public void initJDA() {
-        String token = Settings.getInstance().get("NETNEUTRALITY_BOT_TOKEN");
-        if (token == null) {
-            SessionManager.shutdown();
-            throw new RuntimeException("No bot token provided, exiting.");
-        }
-
-        try {
-            jda = JDABuilder
-                    .createDefault(token)
-                    .enableIntents(GatewayIntent.GUILD_MEMBERS, GatewayIntent.GUILD_MESSAGE_REACTIONS, GatewayIntent.GUILD_VOICE_STATES, GatewayIntent.MESSAGE_CONTENT)
-                    .setActivity(Activity.watching("me load..."))
-                    .build();
-            jda.awaitReady();
-        } catch (InvalidTokenException | IllegalArgumentException | InterruptedException e) {
-            LogHandler.log(e);
-            System.exit(1);
-        }
-    }
-
-    public void shutdown() {
-        System.out.println("[Net Neutrality] Shutting down...");
-        MusicManager.disconnectPlayers();
-        ThreadManager.shutdownExecutor();
-        disconnect();
-        SessionManager.shutdown();
-        System.out.println("[Net Neutrality] Shutdown complete");
-    }
-
-    public JDA getJDA() {
-        return jda;
-    }
-
-    private void disconnect() {
-        if (jda != null) {
-            jda.shutdown();
-        }
-    }
-}

src/main/java/me/bobert/netneutrality/bootstrap/ApplicationContext.java

@@ -0,0 +1,99 @@
+package me.bobert.netneutrality.bootstrap;
+
+/*
+ * Copyright (c) anthorob
+ *
+ * https://discord.gg/qUa6zNFZsd
+ */
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+/**
+ * A small hand-rolled application container that owns wired instances and drives ordered
+ * startup/shutdown.
+ *
+ * <p>Components implementing {@link Lifecycle} are started in ascending {@link Lifecycle#priority()}
+ * order and stopped in the exact reverse order, giving symmetric, deterministic startup and
+ * shutdown without any DI framework.
+ */
+public final class ApplicationContext {
+    private static final Logger logger = LogManager.getLogger(ApplicationContext.class);
+
+    private final List<Lifecycle> components = new ArrayList<>();
+    private final Map<Class<?>, Object> instances = new HashMap<>();
+
+    /**
+     * Registers a component with the context. If the component implements {@link Lifecycle} it will
+     * participate in ordered start/stop. The instance is also indexed by its concrete type and can
+     * be resolved later via {@link #get(Class)}.
+     *
+     * @param component the component to register
+     * @param <T>       the component type
+     * @return the same component, for fluent wiring
+     */
+    public <T> T register(T component) {
+        if (component instanceof Lifecycle lifecycle) {
+            components.add(lifecycle);
+        }
+        instances.put(component.getClass(), component);
+        return component;
+    }
+
+    /**
+     * Resolves a previously registered instance assignable to the given type.
+     *
+     * @param type the requested type
+     * @param <T>  the requested type
+     * @return the matching instance, or {@code null} if none was registered
+     */
+    public <T> T get(Class<T> type) {
+        Object direct = instances.get(type);
+        if (direct != null) {
+            return type.cast(direct);
+        }
+        for (Object instance : instances.values()) {
+            if (type.isInstance(instance)) {
+                return type.cast(instance);
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Starts all registered {@link Lifecycle} components in ascending priority order.
+     *
+     * @throws Exception if any component fails to start
+     */
+    public void start() throws Exception {
+        components.sort(Comparator.comparingInt(Lifecycle::priority));
+        for (Lifecycle component : components) {
+            logger.debug("Starting component {} (priority {})", component.name(), component.priority());
+            component.start();
+        }
+    }
+
+    /**
+     * Stops all registered {@link Lifecycle} components in the reverse of their start order. Failures
+     * are logged and do not prevent the remaining components from being stopped.
+     */
+    public void stop() {
+        List<Lifecycle> reversed = new ArrayList<>(components);
+        reversed.sort(Comparator.comparingInt(Lifecycle::priority));
+        Collections.reverse(reversed);
+        for (Lifecycle component : reversed) {
+            try {
+                logger.debug("Stopping component {} (priority {})", component.name(), component.priority());
+                component.stop();
+            } catch (Exception e) {
+                logger.error("Error while stopping component {}", component.name(), e);
+            }
+        }
+    }
+}

src/main/java/me/bobert/netneutrality/bootstrap/BotState.java

@@ -1,11 +1,13 @@
-package me.bobert.netneutrality.core;
+package me.bobert.netneutrality.bootstrap;
 /*
  * Copyright (c) anthorob
  *
  * https://discord.gg/qUa6zNFZsd
  */
 
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
 import me.bobert.netneutrality.db.service.GuildService;
+import me.bobert.netneutrality.music.MusicService;
 import me.bobert.netneutrality.music.MusicManager;
 import me.bobert.netneutrality.music.TrackScheduler;
 import org.json.JSONArray;
@@ -19,14 +21,32 @@ import java.util.Map;
 public class BotState {
     public static boolean SAFE = false;
 
+    private static volatile GuildServiceProvider guildServices;
+    private static volatile MusicService musicService;
+
+    /**
+     * Binds providers used by the optional state dump. Called once during bootstrap.
+     *
+     * @param guildServices the guild service provider
+     * @param musicService  the music service
+     */
+    public static void bind(GuildServiceProvider guildServices, MusicService musicService) {
+        BotState.guildServices = guildServices;
+        BotState.musicService = musicService;
+    }
+
     //TODO: is it needed?
     private static void saveGuildsState() {
-        Map<String, GuildService> services = GuildService.getServices();
+        if (guildServices == null || musicService == null) {
+            return;
+        }
+
+        Map<String, GuildService> services = guildServices.getServices();
 
         JSONObject main = new JSONObject();
         JSONArray guildsArray = new JSONArray();
 
-        for (MusicManager manager : MusicManager.getManagers()) {
+        for (MusicManager manager : musicService.getManagers()) {
             TrackScheduler trackScheduler = manager.getScheduler();
         }
 

src/main/java/me/bobert/netneutrality/bootstrap/Lifecycle.java

@@ -0,0 +1,56 @@
+package me.bobert.netneutrality.bootstrap;
+
+/*
+ * Copyright (c) anthorob
+ *
+ * https://discord.gg/qUa6zNFZsd
+ */
+
+/**
+ * Contract for a component whose lifecycle is owned and driven by the {@link ApplicationContext}.
+ *
+ * <p>Components are {@linkplain #start() started} in ascending {@link #priority()} order and
+ * {@linkplain #stop() stopped} in the exact reverse order, giving symmetric, deterministic startup
+ * and shutdown without any DI framework. A lower {@code priority()} means the component is started
+ * earlier and, consequently, stopped later.
+ */
+public interface Lifecycle {
+
+    /**
+     * Brings the component up. Called exactly once, during {@link ApplicationContext#start()}.
+     *
+     * @throws Exception if the component cannot be started; startup is aborted
+     */
+    void start() throws Exception;
+
+    /**
+     * Tears the component down, releasing whatever {@link #start()} acquired. Called at most once,
+     * during {@link ApplicationContext#stop()}. Implementations should be null-safe / idempotent so
+     * they can cope with a component that never fully started.
+     *
+     * <p>The default is a no-op for components that hold no resources.
+     *
+     * @throws Exception if teardown fails; the context logs it and continues stopping the rest
+     */
+    default void stop() throws Exception {
+    }
+
+    /**
+     * Relative ordering weight. Lower values start earlier and stop later; equal values keep their
+     * registration order. Defaults to {@code 0}.
+     *
+     * @return the priority of this component
+     */
+    default int priority() {
+        return 0;
+    }
+
+    /**
+     * Human-readable name used in lifecycle diagnostics/logging. Defaults to the simple class name.
+     *
+     * @return a short label identifying this component
+     */
+    default String name() {
+        return getClass().getSimpleName();
+    }
+}

src/main/java/me/bobert/netneutrality/bootstrap/ReflectionHelper.java

@@ -0,0 +1,129 @@
+package me.bobert.netneutrality.bootstrap;
+
+/*
+ * Copyright (c) anthorob
+ *
+ * https://discord.gg/qUa6zNFZsd
+ */
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+import org.reflections.Reflections;
+
+import java.lang.reflect.Constructor;
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Modifier;
+import java.util.Set;
+import java.util.function.BiConsumer;
+import java.util.function.Consumer;
+
+public class ReflectionHelper {
+    private static final Logger logger = LogManager.getLogger(ReflectionHelper.class);
+    private static final BiConsumer<Class<?>, Exception> DEFAULT_FAILURE = (aClass, e) -> logger.error("Failed to load class: {}", aClass.getName(), e);
+
+    public static <E> void loadClassesFromPackage(String packageName, Class<E> clazz, Consumer<E> onInstanciated, BiConsumer<Class<?>, Exception> onFailed) {
+        loadClassesFromPackage(packageName, clazz, null, onInstanciated, onFailed);
+    }
+
+    /**
+     * Discovers concrete subtypes of {@code clazz} under {@code packageName} and instantiates each
+     * one. When a non-null {@link ApplicationContext} is provided, prefers the public constructor
+     * with the most parameters whose every parameter type is resolvable via
+     * {@link ApplicationContext#get(Class)}; otherwise (or when no such constructor exists) falls
+     * back to the no-arg constructor.
+     *
+     * @param packageName    root package to scan
+     * @param clazz          base type of classes to load
+     * @param context        optional DI context used for constructor injection; {@code null} keeps
+     *                       legacy no-arg construction only
+     * @param onInstanciated callback invoked with each successfully created instance
+     * @param onFailed       callback invoked when a class cannot be instantiated
+     * @param <E>            the base type
+     */
+    public static <E> void loadClassesFromPackage(String packageName, Class<E> clazz, ApplicationContext context, Consumer<E> onInstanciated, BiConsumer<Class<?>, Exception> onFailed) {
+        Set<Class<? extends E>> classes = new Reflections(packageName).getSubTypesOf(clazz);
+        for (Class<? extends E> s : classes) {
+            try {
+                if (Modifier.isAbstract(s.getModifiers())) {
+                    continue;
+                }
+
+                E instance = instantiate(s, context);
+                onInstanciated.accept(instance);
+            } catch (InstantiationException | IllegalAccessException | IllegalArgumentException
+                     | InvocationTargetException | NoSuchMethodException | SecurityException e) {
+                onFailed.accept(s, e);
+            }
+        }
+    }
+
+    /**
+     * Instantiates {@code type} using context-based constructor injection when possible.
+     *
+     * <p>Selection algorithm: among public constructors, pick the one with the most parameters for
+     * which every parameter type resolves to a non-null value via {@code context.get(paramType)}.
+     * If no such constructor exists (or {@code context} is null), fall back to the public no-arg
+     * constructor.
+     */
+    @SuppressWarnings("unchecked")
+    public static <E> E instantiate(Class<? extends E> type, ApplicationContext context)
+        throws InstantiationException, IllegalAccessException, InvocationTargetException, NoSuchMethodException {
+        if (context != null) {
+            Constructor<?> best = null;
+            Object[] bestArgs = null;
+
+            for (Constructor<?> ctor : type.getConstructors()) {
+                Class<?>[] paramTypes = ctor.getParameterTypes();
+                if (paramTypes.length == 0) {
+                    continue;
+                }
+
+                Object[] args = new Object[paramTypes.length];
+                boolean resolvable = true;
+                for (int i = 0; i < paramTypes.length; i++) {
+                    Object dependency = context.get(paramTypes[i]);
+                    if (dependency == null) {
+                        resolvable = false;
+                        break;
+                    }
+                    args[i] = dependency;
+                }
+
+                if (resolvable && (best == null || paramTypes.length > best.getParameterCount())) {
+                    best = ctor;
+                    bestArgs = args;
+                }
+            }
+
+            if (best != null) {
+                return (E) best.newInstance(bestArgs);
+            }
+        }
+
+        return type.getConstructor().newInstance();
+    }
+
+    public static <E> void loadCommands(Class<E> clazz, Consumer<E> onInstanciated, BiConsumer<Class<?>, Exception> onFailed) {
+        loadClassesFromPackage("me.bobert.netneutrality", clazz, onInstanciated, onFailed);
+    }
+
+    public static <E> void loadCommands(Class<E> clazz, Consumer<E> onInstanciated) {
+        loadClassesFromPackage("me.bobert.netneutrality", clazz, onInstanciated, DEFAULT_FAILURE);
+    }
+
+    public static <E> void loadCommands(Class<E> clazz, ApplicationContext context, Consumer<E> onInstanciated) {
+        loadClassesFromPackage("me.bobert.netneutrality", clazz, context, onInstanciated, DEFAULT_FAILURE);
+    }
+
+    public static <E> void loadTasks(Class<E> clazz, Consumer<E> onInstanciated, BiConsumer<Class<?>, Exception> onFailed) {
+        loadClassesFromPackage("me.bobert.netneutrality", clazz, onInstanciated, onFailed);
+    }
+
+    public static <E> void loadTasks(Class<E> clazz, Consumer<E> onInstanciated) {
+        loadClassesFromPackage("me.bobert.netneutrality", clazz, onInstanciated, DEFAULT_FAILURE);
+    }
+
+    public static <E> void loadTasks(Class<E> clazz, ApplicationContext context, Consumer<E> onInstanciated) {
+        loadClassesFromPackage("me.bobert.netneutrality", clazz, context, onInstanciated, DEFAULT_FAILURE);
+    }
+}

src/main/java/me/bobert/netneutrality/command/admin/BlacklistCommand.java

@@ -5,20 +5,29 @@ package me.bobert.netneutrality.command.admin;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractAdminCommand;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.AdminCommand;
 import me.bobert.netneutrality.core.command.options.CommandOption;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.db.entities.OBlacklist;
 import me.bobert.netneutrality.db.service.BlacklistService;
-import me.bobert.netneutrality.db.service.GuildService;
 import net.dv8tion.jda.api.interactions.commands.OptionType;
 import net.dv8tion.jda.api.interactions.commands.build.SubcommandData;
 
 import java.util.List;
+import java.util.Objects;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+
+public class BlacklistCommand extends AdminCommand {
+
+    private final GuildServiceProvider guildServices;
+
+    public BlacklistCommand(GuildServiceProvider guildServices) {
+        Objects.requireNonNull(guildServices, "GuildServiceProvider must not be null");
+        this.guildServices = guildServices;
+    }
 
-public class BlacklistCommand extends AbstractAdminCommand {
 
     @Override
     public boolean isEnabled() {
@@ -43,11 +52,11 @@ public class BlacklistCommand extends AbstractAdminCommand {
     @Override
     public void registerCommandOptions(CommandOptionsBuilder builder) {
         builder.addSubcommands(
-                new SubcommandData("get", "Get all blacklisted words for this guild"),
+            new SubcommandData("get", "Get all blacklisted words for this guild"),
-                new SubcommandData("add", "Add a word to the blacklist")
+            new SubcommandData("add", "Add a word to the blacklist")
-                        .addOption(OptionType.STRING, "word", "Word to add", true),
+                .addOption(OptionType.STRING, "word", "Word to add", true),
-                new SubcommandData("remove", "Remove a word from the blacklist")
+            new SubcommandData("remove", "Remove a word from the blacklist")
-                        .addOption(OptionType.STRING, "word", "Word to remove", true)
+                .addOption(OptionType.STRING, "word", "Word to remove", true)
         );
     }
 
@@ -55,7 +64,7 @@ public class BlacklistCommand extends AbstractAdminCommand {
     public CommandExecutionResult execute(CommandContext context) {
         String sub = context.getSubcommand();
         String word = context.getOption("word", "", CommandOption::getAsString);
-        BlacklistService service = GuildService.get(context.getGuild()).getBlacklistService();
+        BlacklistService service = guildServices.get(context.getGuild()).getBlacklistService();
 
         switch (sub) {
             case "get" -> context.async("Retrieving list, please wait...", asyncMessage -> {

src/main/java/me/bobert/netneutrality/command/admin/PurgeCommand.java

@@ -0,0 +1,78 @@
+package me.bobert.netneutrality.command.admin;
+/*
+ * Copyright (c) anthorob
+ *
+ * https://discord.gg/qUa6zNFZsd
+ */
+
+import me.bobert.netneutrality.core.command.CommandCategory;
+import me.bobert.netneutrality.core.command.CommandExecutionResult;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.AbstractCommand;
+import me.bobert.netneutrality.core.command.options.CommandOption;
+import me.bobert.netneutrality.core.context.CommandContext;
+import me.bobert.netneutrality.utils.ChannelMessagePurger;
+import net.dv8tion.jda.api.entities.channel.middleman.GuildMessageChannel;
+import net.dv8tion.jda.api.interactions.commands.OptionType;
+import net.dv8tion.jda.api.interactions.commands.build.OptionData;
+
+public class PurgeCommand extends AbstractCommand {
+
+    @Override
+    public boolean needAdmin() {
+        return true;
+    }
+
+    @Override
+    public boolean isEnabled() {
+        return false;
+    }
+
+    @Override
+    public boolean isGuildOnly() {
+        return true;
+    }
+
+    @Override
+    public String getCommandName() {
+        return "purge";
+    }
+
+    @Override
+    public String getDescription() {
+        return "Delete messages from the channel you are currently on";
+    }
+
+    @Override
+    public void registerCommandOptions(CommandOptionsBuilder builder) {
+        builder.addOptions(
+            new OptionData(OptionType.INTEGER, "to-purge", "Number of messages to delete (max 2500)", true)
+                .setRequiredRange(1, 2500));
+    }
+
+    @Override
+    public CommandCategory getCategory() {
+        return CommandCategory.ADMINISTRATION;
+    }
+
+    @Override
+    public CommandExecutionResult execute(CommandContext context) {
+        int toDelete = context.getOption("to-purge", 0, CommandOption::getAsInt);
+        context.ephemeral();
+
+        if (toDelete > 0) {
+            GuildMessageChannel messageChannel = (GuildMessageChannel) context.getChannel();
+            ChannelMessagePurger channelMessagePurger = ChannelMessagePurger.getPurger(messageChannel);
+            boolean lock = channelMessagePurger.canLockBeAcquired();
+            channelMessagePurger.purgeMessages(context, toDelete);
+
+            context.reply("Processing purge command.. This can take some time.");
+
+            if (!lock) {
+                context.reply("Another purge is currently in progress on this channel, please wait before purging again");
+            }
+        }
+
+        return CommandExecutionResult.none();
+    }
+}

src/main/java/me/bobert/netneutrality/command/admin/ReactionCommand.java

@@ -5,13 +5,12 @@ package me.bobert.netneutrality.command.admin;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractAdminCommand;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.AdminCommand;
 import me.bobert.netneutrality.core.command.options.CommandOption;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
 import me.bobert.netneutrality.core.context.CommandContext;
-import me.bobert.netneutrality.core.tasks.TaskManager;
+import me.bobert.netneutrality.tasks.reaction.EmojiReactionRoleTask;
-import me.bobert.netneutrality.tasks.emoji.EmojiReactionRoleTask;
 import net.dv8tion.jda.api.entities.Message;
 import net.dv8tion.jda.api.entities.Role;
 import net.dv8tion.jda.api.interactions.commands.OptionType;
@@ -23,8 +22,17 @@ import java.util.List;
 import java.util.Map;
 import java.util.Objects;
 import java.util.stream.Collectors;
+import me.bobert.netneutrality.core.tasks.TaskManager;
+
+public class ReactionCommand extends AdminCommand {
+
+    private final TaskManager taskManager;
+
+    public ReactionCommand(TaskManager taskManager) {
+        Objects.requireNonNull(taskManager, "TaskManager must not be null");
+        this.taskManager = taskManager;
+    }
 
-public class ReactionCommand extends AbstractAdminCommand {
 
     @Override
     public boolean isEnabled() {
@@ -49,30 +57,30 @@ public class ReactionCommand extends AbstractAdminCommand {
     @Override
     public void registerCommandOptions(CommandOptionsBuilder builder) {
         builder.addSubcommandGroups(
-                new SubcommandGroupData("emoji", "Give roles to users using emojis").addSubcommands(
+            new SubcommandGroupData("emoji", "Give roles to users using emojis").addSubcommands(
-                        new SubcommandData("list", "Lists all registered tasks for this guild"),
+                new SubcommandData("list", "Lists all registered tasks for this guild"),
-                        new SubcommandData("setup", "Add a role to a message").addOptions(
+                new SubcommandData("setup", "Add a role to a message").addOptions(
-                                new OptionData(OptionType.STRING, "messageid", "The ID of the message", true)
+                    new OptionData(OptionType.STRING, "messageid", "The ID of the message", true)
-                                        .setRequiredLength(19, 19),
+                        .setRequiredLength(19, 19),
-                                new OptionData(OptionType.STRING, "emoji", "Emoji associated with the role", true),
+                    new OptionData(OptionType.STRING, "emoji", "Emoji associated with the role", true),
-                                new OptionData(OptionType.ROLE, "role", "Role to add to the emoji", true)
+                    new OptionData(OptionType.ROLE, "role", "Role to add to the emoji", true)
-                        ),
+                ),
-                        new SubcommandData("add", "Add a role to an existing message").addOptions(
+                new SubcommandData("add", "Add a role to an existing message").addOptions(
-                                new OptionData(OptionType.STRING, "messageid", "The ID of the message", true)
+                    new OptionData(OptionType.STRING, "messageid", "The ID of the message", true)
-                                        .setRequiredLength(19, 19),
+                        .setRequiredLength(19, 19),
-                                new OptionData(OptionType.STRING, "emoji", "Emoji associated with the role", true),
+                    new OptionData(OptionType.STRING, "emoji", "Emoji associated with the role", true),
-                                new OptionData(OptionType.ROLE, "role", "Role to add to the emoji", true)
+                    new OptionData(OptionType.ROLE, "role", "Role to add to the emoji", true)
-                        ),
+                ),
-                        new SubcommandData("remove", "Remove a role from a message").addOptions(
+                new SubcommandData("remove", "Remove a role from a message").addOptions(
-                                new OptionData(OptionType.STRING, "messageid", "The ID of the message", true)
+                    new OptionData(OptionType.STRING, "messageid", "The ID of the message", true)
-                                        .setRequiredLength(19, 19),
+                        .setRequiredLength(19, 19),
-                                new OptionData(OptionType.STRING, "emoji", "Emoji to remove from the message", true)
+                    new OptionData(OptionType.STRING, "emoji", "Emoji to remove from the message", true)
-                        ),
+                ),
-                        new SubcommandData("delete", "Remove all roles from a message").addOptions(
+                new SubcommandData("delete", "Remove all roles from a message").addOptions(
-                                new OptionData(OptionType.STRING, "messageid", "The ID of the message", true)
+                    new OptionData(OptionType.STRING, "messageid", "The ID of the message", true)
-                                        .setRequiredLength(19, 19)
+                        .setRequiredLength(19, 19)
-                        )
                 )
+            )
         );
     }
 
@@ -93,11 +101,11 @@ public class ReactionCommand extends AbstractAdminCommand {
 
     private CommandExecutionResult executeEmoji(CommandContext context, String guildId, String messageId, String sub) {
         String id = String.format("%s:%s", guildId, messageId);
-        EmojiReactionRoleTask task = (EmojiReactionRoleTask) TaskManager.getInstance().getTask(id);
+        EmojiReactionRoleTask task = (EmojiReactionRoleTask) taskManager.getTask(id);
 
         switch (sub) {
             case "list" -> {
-                List<EmojiReactionRoleTask> tasks = TaskManager.getInstance().findTasksByPartialId(EmojiReactionRoleTask.class, guildId);
+                List<EmojiReactionRoleTask> tasks = taskManager.findTasksByPartialId(EmojiReactionRoleTask.class, guildId);
                 if (tasks.isEmpty()) {
                     return CommandExecutionResult.info("No tasks found for this guild");
                 }
@@ -107,24 +115,24 @@ public class ReactionCommand extends AbstractAdminCommand {
 
                 for (EmojiReactionRoleTask item : tasks) {
                     Map<String, String> mapping = item.getEmojiMapping().entrySet().stream()
-                            .map(entry -> {
+                        .map(entry -> {
-                                Role role = context.getGuild().getRoleById(entry.getValue());
+                            Role role = context.getGuild().getRoleById(entry.getValue());
-                                return role != null ? Map.entry(entry.getKey(), role.getAsMention()) : null;
+                            return role != null ? Map.entry(entry.getKey(), role.getAsMention()) : null;
-                            })
+                        })
-                            .filter(Objects::nonNull)
+                        .filter(Objects::nonNull)
-                            .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue));
+                        .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue));
 
                     builder.append("\n- Task ID: ").append(item.getId()).append("\n")
-                            .append("  Message: ")
+                        .append("  Message: ")
-                            .append(String.format(Message.JUMP_URL, item.getGuildId(), item.getChannelId(), item.getMessageId()))
+                        .append(String.format(Message.JUMP_URL, item.getGuildId(), item.getChannelId(), item.getMessageId()))
-                            .append("\n")
+                        .append("\n")
-                            .append("  Emoji Mappings:\n");
+                        .append("  Emoji Mappings:\n");
 
                     if (mapping.isEmpty()) {
                         builder.append("  No emoji mappings found\n");
                     } else {
                         mapping.forEach((emoji, roleMention) ->
-                                builder.append("    - ").append(emoji).append(" → ").append(roleMention).append("\n")
+                            builder.append("    - ").append(emoji).append(" → ").append(roleMention).append("\n")
                         );
                     }
                 }

src/main/java/me/bobert/netneutrality/command/basic/HelpCommand.java

@@ -5,23 +5,40 @@ package me.bobert.netneutrality.command.basic;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.*;
+import me.bobert.netneutrality.core.command.CommandCategory;
+import me.bobert.netneutrality.core.command.CommandContainer;
+import me.bobert.netneutrality.core.command.CommandExecutionResult;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.AbstractCommand;
 import me.bobert.netneutrality.core.command.options.CommandOption;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
 import me.bobert.netneutrality.core.context.CommandContext;
-import me.bobert.netneutrality.core.tasks.BuiltInTask;
+import me.bobert.netneutrality.core.tasks.trait.WithButton;
+import me.bobert.netneutrality.core.command.CommandRegistry;
+import me.bobert.netneutrality.core.tasks.TaskManager;
 import me.bobert.netneutrality.tasks.help.BotInfo;
 import me.bobert.netneutrality.tasks.help.CommandHelp;
 import me.bobert.netneutrality.tasks.help.ReportBug;
-import me.bobert.netneutrality.utils.MessageFunction;
+import me.bobert.netneutrality.shared.util.MessageFunction;
+import net.dv8tion.jda.api.components.actionrow.ActionRow;
+import net.dv8tion.jda.api.components.buttons.Button;
 import net.dv8tion.jda.api.interactions.commands.OptionType;
-import net.dv8tion.jda.api.interactions.components.ActionRow;
-import net.dv8tion.jda.api.interactions.components.buttons.Button;
 
 import java.util.List;
 
 public class HelpCommand extends AbstractCommand {
 
+    private final CommandRegistry commands;
+    private final TaskManager taskManager;
+
+    public HelpCommand() {
+        this(null, null);
+    }
+
+    public HelpCommand(CommandRegistry commands, TaskManager taskManager) {
+        this.commands = commands;
+        this.taskManager = taskManager;
+    }
+
     @Override
     public boolean needAdmin() {
         return false;
@@ -61,15 +78,15 @@ public class HelpCommand extends AbstractCommand {
     public CommandExecutionResult execute(CommandContext context) {
         String command = context.getOption("command", null, CommandOption::getAsString);
         if (command == null) {
-            Button commands = BuiltInTask.createButton(CommandHelp.class);
+            Button commandsBtn = createTaskButton(CommandHelp.class);
-            Button info = BuiltInTask.createButton(BotInfo.class);
+            Button info = createTaskButton(BotInfo.class);
-            Button reportbug = BuiltInTask.createButton(ReportBug.class);
+            Button reportbug = createTaskButton(ReportBug.class);
-            ActionRow row = ActionRow.of(commands, info, reportbug);
+            ActionRow row = ActionRow.of(commandsBtn, info, reportbug);
             context.replyEphemeral("Thanks for using the Net Neutrality Bot! What do you need help with?", List.of(row));
             return CommandExecutionResult.none();
         }
 
-        CommandContainer container = CommandManager.getCommandContainer(command);
+        CommandContainer container = commands.getCommandContainer(command);
         if (container.getCommand() == null) {
             return CommandExecutionResult.warn("Command does not exist");
         }
@@ -77,4 +94,12 @@ public class HelpCommand extends AbstractCommand {
         context.replyEphemeral(MessageFunction.buildCommandHelpMessage(container));
         return CommandExecutionResult.none();
     }
+
+    private Button createTaskButton(Class<? extends WithButton> clazz) {
+        WithButton withButton = taskManager.findButtonTaskByClass(clazz);
+        if (withButton == null) {
+            throw new IllegalArgumentException("Task " + clazz.getName() + " was not registered by the task manager.");
+        }
+        return withButton.createButton();
+    }
 }

src/main/java/me/bobert/netneutrality/command/basic/PingCommand.java

@@ -5,10 +5,10 @@ package me.bobert.netneutrality.command.basic;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractCommand;
 import me.bobert.netneutrality.core.command.CommandCategory;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.AbstractCommand;
 import me.bobert.netneutrality.core.context.CommandContext;
 
 public class PingCommand extends AbstractCommand {

src/main/java/me/bobert/netneutrality/command/bot/ConfigureCommand.java

@@ -5,14 +5,13 @@ package me.bobert.netneutrality.command.bot;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractAdminCommand;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.AdminCommand;
 import me.bobert.netneutrality.core.command.options.CommandOption;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.db.GSettings;
 import me.bobert.netneutrality.db.service.GuildService;
-import me.bobert.netneutrality.music.MusicManager;
 import net.dv8tion.jda.api.entities.Role;
 import net.dv8tion.jda.api.entities.channel.concrete.TextChannel;
 import net.dv8tion.jda.api.entities.channel.unions.GuildChannelUnion;
@@ -22,8 +21,23 @@ import net.dv8tion.jda.api.interactions.commands.build.SubcommandData;
 import net.dv8tion.jda.api.utils.messages.MessageCreateBuilder;
 
 import java.util.Map;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+import me.bobert.netneutrality.music.MusicService;
+
+public class ConfigureCommand extends AdminCommand {
+
+    private final GuildServiceProvider guildServices;
+    private final MusicService musicService;
+
+    public ConfigureCommand() {
+        this(null, null);
+    }
+
+    public ConfigureCommand(GuildServiceProvider guildServices, MusicService musicService) {
+        this.guildServices = guildServices;
+        this.musicService = musicService;
+    }
 
-public class ConfigureCommand extends AbstractAdminCommand {
 
     @Override
     public boolean isEnabled() {
@@ -48,22 +62,22 @@ public class ConfigureCommand extends AbstractAdminCommand {
     @Override
     public void registerCommandOptions(CommandOptionsBuilder builder) {
         builder.addSubcommands(
-                new SubcommandData("music-volume", "Volume for the music player")
+            new SubcommandData("music-volume", "Volume for the music player")
-                        .addOptions(new OptionData(OptionType.INTEGER, "volume", "Playback volume for every session", true)
+                .addOptions(new OptionData(OptionType.INTEGER, "volume", "Playback volume for every session", true)
-                                .setRequiredRange(0, 100)),
+                    .setRequiredRange(0, 100)),
-                new SubcommandData("error-logging", "Send errors to #error and/or #log channel")
+            new SubcommandData("error-logging", "Send errors to #error and/or #log channel")
-                        .addOption(OptionType.BOOLEAN, "debug", "Enable or disable the fonctionnality", true),
+                .addOption(OptionType.BOOLEAN, "debug", "Enable or disable the fonctionnality", true),
-                new SubcommandData("music-role", "Role needed to use music commands")
+            new SubcommandData("music-role", "Role needed to use music commands")
-                        .addOption(OptionType.ROLE, "role", "Name of role", true),
+                .addOption(OptionType.ROLE, "role", "Name of role", true),
-                new SubcommandData("music-channel", "Only allow music commands on this channel")
+            new SubcommandData("music-channel", "Only allow music commands on this channel")
-                        .addOption(OptionType.CHANNEL, "channel", "Leave empty to allow everywhere")
+                .addOption(OptionType.CHANNEL, "channel", "Leave empty to allow everywhere")
         );
     }
 
     @Override
     public CommandExecutionResult execute(CommandContext context) {
         String sub = context.getSubcommand();
-        GuildService guildService = GuildService.get(context.getGuild().getId());
+        GuildService guildService = guildServices.get(context.getGuild().getId());
         context.ephemeral();
 
         if ("music-role".equals(sub)) {
@@ -105,7 +119,7 @@ public class ConfigureCommand extends AbstractAdminCommand {
         if ("music-volume".equals(sub)) {
             int volume = context.getOption("volume", 30, CommandOption::getAsInt);
             guildService.getGuildSettingService().setSettingValue(GSettings.MUSIC_VOLUME, String.valueOf(volume));
-            MusicManager.get(context.getGuild()).setVolume(volume);
+            musicService.get(context.getGuild()).setVolume(volume);
 
             return CommandExecutionResult.success(String.format("Default volume for music player is now %d", volume));
         }

src/main/java/me/bobert/netneutrality/command/crypto/CryptoPriceCommand.java

@@ -6,11 +6,11 @@ package me.bobert.netneutrality.command.crypto;
  */
 
 import me.bobert.netneutrality.core.LogHandler;
-import me.bobert.netneutrality.core.command.AbstractCommand;
 import me.bobert.netneutrality.core.command.CommandCategory;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.AbstractCommand;
 import me.bobert.netneutrality.core.command.options.CommandOption;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.http.WebModule;
 import net.dv8tion.jda.api.interactions.commands.OptionType;
@@ -56,9 +56,9 @@ public class CryptoPriceCommand extends AbstractCommand {
     @Override
     public void registerCommandOptions(CommandOptionsBuilder builder) {
         builder.addOptions(
-                new OptionData(OptionType.STRING, "symbol", "The crypto symbol to fetch price for", true),
+            new OptionData(OptionType.STRING, "symbol", "The crypto symbol to fetch price for", true),
-                new OptionData(OptionType.STRING, "currency", "In which currency should the price be displayed")
+            new OptionData(OptionType.STRING, "currency", "In which currency should the price be displayed")
-                        .setRequiredLength(3, 3)
+                .setRequiredLength(3, 3)
         );
     }
 
@@ -118,9 +118,9 @@ public class CryptoPriceCommand extends AbstractCommand {
             JSONObject json = http.getAsObject();
 
             JSONObject pairs = json.getJSONObject("Data")
-                    .getJSONObject("exchanges")
+                .getJSONObject("exchanges")
-                    .getJSONObject(exchange)
+                .getJSONObject(exchange)
-                    .getJSONObject("pairs");
+                .getJSONObject("pairs");
 
             return pairs.has(symbol);
 

src/main/java/me/bobert/netneutrality/command/custom/.gitignore

@@ -1 +1 @@
-*.java
+**/*.java

src/main/java/me/bobert/netneutrality/command/git/ReportIssueCommand.java

@@ -5,19 +5,31 @@ package me.bobert.netneutrality.command.git;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.context.command.SlashCommandContext;
-import me.bobert.netneutrality.core.command.AbstractCommand;
 import me.bobert.netneutrality.core.command.CommandCategory;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.AbstractCommand;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.http.WebModule;
 import me.bobert.netneutrality.tasks.git.ReportIssueTask;
-import me.bobert.netneutrality.utils.Settings;
 
+import java.util.Objects;
 import java.util.concurrent.TimeUnit;
+import me.bobert.netneutrality.core.tasks.TaskManager;
+import me.bobert.netneutrality.utils.SettingsProvider;
 
 public class ReportIssueCommand extends AbstractCommand {
+
+    private final SettingsProvider settings;
+    private final TaskManager taskManager;
+
+    public ReportIssueCommand(SettingsProvider settings, TaskManager taskManager) {
+        Objects.requireNonNull(settings, "SettingsProvider must not be null");
+        Objects.requireNonNull(taskManager, "TaskManager must not be null");
+        this.settings = settings;
+        this.taskManager = taskManager;
+    }
+
     @Override
     public boolean needAdmin() {
         return false;
@@ -60,16 +72,16 @@ public class ReportIssueCommand extends AbstractCommand {
 
     @Override
     public CommandExecutionResult execute(CommandContext context) {
-        String gitlabHost = Settings.getInstance().get("GITLAB_HOST");
+        String gitlabHost = settings.get("GITLAB_HOST");
-        String gitlabToken = Settings.getInstance().get("GITLAB_TOKEN");
+        String gitlabToken = settings.get("GITLAB_TOKEN");
-        String projectId = Settings.getInstance().get("GITLAB_PROJECT_ID");
+        String projectId = settings.get("GITLAB_PROJECT_ID");
 
         if (gitlabHost == null || gitlabToken == null || projectId == null) {
             return CommandExecutionResult.error("Command is not configured, failed to create issue.");
         }
 
         if (new WebModule.Builder(gitlabHost).ping().timeout(2, TimeUnit.SECONDS).build().request().isSuccess()) {
-            return CommandExecutionResult.task(new ReportIssueTask(context));
+            return CommandExecutionResult.task(new ReportIssueTask(taskManager, context, settings));
         }
 
         return CommandExecutionResult.error("Unable to create bug reports at this time, please try again later.");

src/main/java/me/bobert/netneutrality/command/music/BitconnectCommand.java

@@ -6,14 +6,31 @@ package me.bobert.netneutrality.command.music;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractMusicCommand;
 import me.bobert.netneutrality.core.command.CommandCategory;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.MusicCommand;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+import me.bobert.netneutrality.music.MusicService;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.music.MusicManager;
 
-public class BitconnectCommand extends AbstractMusicCommand {
+public class BitconnectCommand extends MusicCommand {
+
+    private final MusicService musicService;
+
+    public BitconnectCommand() {
+        this(null, null);
+    }
+
+    public BitconnectCommand(MusicService musicService) {
+        this(musicService, null);
+    }
+
+    public BitconnectCommand(MusicService musicService, GuildServiceProvider guildServices) {
+        super(guildServices);
+        this.musicService = musicService;
+    }
 
     @Override
     public boolean isEnabled() {
@@ -42,7 +59,7 @@ public class BitconnectCommand extends AbstractMusicCommand {
 
     @Override
     public CommandExecutionResult execute(CommandContext context) {
-        MusicManager manager = MusicManager.get(context.getGuild());
+        MusicManager manager = musicService.get(context.getGuild());
         context.ephemeral();
         context.deleteMessage();
 

src/main/java/me/bobert/netneutrality/command/music/ClearQueueCommand.java

@@ -6,14 +6,31 @@ package me.bobert.netneutrality.command.music;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractMusicCommand;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.MusicCommand;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+import me.bobert.netneutrality.music.MusicService;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.music.MusicManager;
 import me.bobert.netneutrality.utils.MusicUtils;
 
-public class ClearQueueCommand extends AbstractMusicCommand {
+public class ClearQueueCommand extends MusicCommand {
+
+    private final MusicService musicService;
+
+    public ClearQueueCommand() {
+        this(null, null);
+    }
+
+    public ClearQueueCommand(MusicService musicService) {
+        this(musicService, null);
+    }
+
+    public ClearQueueCommand(MusicService musicService, GuildServiceProvider guildServices) {
+        super(guildServices);
+        this.musicService = musicService;
+    }
 
     @Override
     public boolean needAdmin() {
@@ -42,10 +59,10 @@ public class ClearQueueCommand extends AbstractMusicCommand {
 
     @Override
     public CommandExecutionResult execute(CommandContext context) {
-        MusicManager manager = MusicManager.get(context.getGuild());
+        MusicManager manager = musicService.get(context.getGuild());
         context.ack();
 
-        if (MusicUtils.checkIfConnected(context)) {
+        if (MusicUtils.checkIfConnected(context, manager)) {
             return manager.getQueueManager().clearQueue();
         }
 

src/main/java/me/bobert/netneutrality/command/music/CurrentlyPlayingCommand.java

@@ -6,15 +6,32 @@ package me.bobert.netneutrality.command.music;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractMusicCommand;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.MusicCommand;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+import me.bobert.netneutrality.music.MusicService;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.music.MusicManager;
-import me.bobert.netneutrality.utils.MessageFunction;
+import me.bobert.netneutrality.shared.util.MessageFunction;
 import me.bobert.netneutrality.utils.MusicUtils;
 
-public class CurrentlyPlayingCommand extends AbstractMusicCommand {
+public class CurrentlyPlayingCommand extends MusicCommand {
+
+    private final MusicService musicService;
+
+    public CurrentlyPlayingCommand() {
+        this(null, null);
+    }
+
+    public CurrentlyPlayingCommand(MusicService musicService) {
+        this(musicService, null);
+    }
+
+    public CurrentlyPlayingCommand(MusicService musicService, GuildServiceProvider guildServices) {
+        super(guildServices);
+        this.musicService = musicService;
+    }
 
     @Override
     public boolean isEnabled() {
@@ -38,10 +55,10 @@ public class CurrentlyPlayingCommand extends AbstractMusicCommand {
 
     @Override
     public CommandExecutionResult execute(CommandContext context) {
-        MusicManager manager = MusicManager.get(context.getGuild());
+        MusicManager manager = musicService.get(context.getGuild());
         context.ack();
 
-        if (MusicUtils.checkIfConnected(context)) {
+        if (MusicUtils.checkIfConnected(context, manager)) {
             if (!manager.isCurrentlyPlaying()) {
                 return CommandExecutionResult.info("Bot isn't playing any tracks right now");
             }

src/main/java/me/bobert/netneutrality/command/music/JoinCommand.java

@@ -6,13 +6,31 @@ package me.bobert.netneutrality.command.music;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractMusicCommand;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.MusicCommand;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+import me.bobert.netneutrality.music.MusicService;
+import me.bobert.netneutrality.music.MusicManager;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.utils.MusicUtils;
 
-public class JoinCommand extends AbstractMusicCommand {
+public class JoinCommand extends MusicCommand {
+
+    private final MusicService musicService;
+
+    public JoinCommand() {
+        this(null, null);
+    }
+
+    public JoinCommand(MusicService musicService) {
+        this(musicService, null);
+    }
+
+    public JoinCommand(MusicService musicService, GuildServiceProvider guildServices) {
+        super(guildServices);
+        this.musicService = musicService;
+    }
 
     @Override
     public boolean isEnabled() {
@@ -36,7 +54,9 @@ public class JoinCommand extends AbstractMusicCommand {
 
     @Override
     public CommandExecutionResult execute(CommandContext context) {
-        if (MusicUtils.connect(context)) {
+        MusicManager manager = musicService.get(context.getGuild());
+
+        if (MusicUtils.connect(context, manager)) {
             context.reply("Joining current voice channel");
         }
 

src/main/java/me/bobert/netneutrality/command/music/LeaveCommand.java

@@ -6,14 +6,38 @@ package me.bobert.netneutrality.command.music;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractMusicCommand;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.MusicCommand;
 import me.bobert.netneutrality.core.context.CommandContext;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+import me.bobert.netneutrality.music.MusicService;
 import me.bobert.netneutrality.music.MusicManager;
 import me.bobert.netneutrality.utils.MusicUtils;
 
-public class LeaveCommand extends AbstractMusicCommand {
+/**
+ * Leaves the voice channel for the current guild.
+ *
+ * <p>Representative command migrated to constructor injection of {@link MusicService} (and optional
+ * {@link GuildServiceProvider} for the {@link MusicCommand} base). The no-arg constructor remains as
+ * a fallback for non-DI loaders.
+ */
+public class LeaveCommand extends MusicCommand {
+
+    private final MusicService musicService;
+
+    public LeaveCommand() {
+        this(null, null);
+    }
+
+    public LeaveCommand(MusicService musicService) {
+        this(musicService, null);
+    }
+
+    public LeaveCommand(MusicService musicService, GuildServiceProvider guildServices) {
+        super(guildServices);
+        this.musicService = musicService;
+    }
 
     @Override
     public boolean isEnabled() {
@@ -37,9 +61,9 @@ public class LeaveCommand extends AbstractMusicCommand {
 
     @Override
     public CommandExecutionResult execute(CommandContext context) {
-        MusicManager manager = MusicManager.get(context.getGuild());
+        MusicManager manager = musicService.get(context.getGuild());
 
-        if (MusicUtils.checkIfConnected(context)) {
+        if (MusicUtils.checkIfConnected(context, manager)) {
             context.reply("Leaving voice channel and clearing queue");
             manager.disconnect();
         }

src/main/java/me/bobert/netneutrality/command/music/PlayCommand.java

@@ -6,15 +6,32 @@ package me.bobert.netneutrality.command.music;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractMusicCommand;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.MusicCommand;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+import me.bobert.netneutrality.music.MusicService;
 import me.bobert.netneutrality.core.command.options.CommandOption;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.music.MusicManager;
 import net.dv8tion.jda.api.interactions.commands.OptionType;
 
-public class PlayCommand extends AbstractMusicCommand {
+public class PlayCommand extends MusicCommand {
+
+    private final MusicService musicService;
+
+    public PlayCommand() {
+        this(null, null);
+    }
+
+    public PlayCommand(MusicService musicService) {
+        this(musicService, null);
+    }
+
+    public PlayCommand(MusicService musicService, GuildServiceProvider guildServices) {
+        super(guildServices);
+        this.musicService = musicService;
+    }
 
     @Override
     public boolean isEnabled() {
@@ -38,7 +55,7 @@ public class PlayCommand extends AbstractMusicCommand {
 
     @Override
     public CommandExecutionResult execute(CommandContext context) {
-        MusicManager manager = MusicManager.get(context.getGuild());
+        MusicManager manager = musicService.get(context.getGuild());
         String query = context.getOption("query", CommandOption::getAsString);
         context.ack();
 

src/main/java/me/bobert/netneutrality/command/music/QueueCommand.java

@@ -5,20 +5,37 @@ package me.bobert.netneutrality.command.music;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractMusicCommand;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.MusicCommand;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+import me.bobert.netneutrality.music.MusicService;
 import me.bobert.netneutrality.core.command.options.CommandOption;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.music.MusicManager;
-import me.bobert.netneutrality.utils.MessageFunction;
+import me.bobert.netneutrality.shared.util.MessageFunction;
 import me.bobert.netneutrality.utils.MusicUtils;
 import net.dv8tion.jda.api.entities.Member;
 import net.dv8tion.jda.api.interactions.commands.OptionType;
 import net.dv8tion.jda.api.interactions.commands.build.OptionData;
 import net.dv8tion.jda.api.interactions.commands.build.SubcommandData;
 
-public class QueueCommand extends AbstractMusicCommand {
+public class QueueCommand extends MusicCommand {
+
+    private final MusicService musicService;
+
+    public QueueCommand() {
+        this(null, null);
+    }
+
+    public QueueCommand(MusicService musicService) {
+        this(musicService, null);
+    }
+
+    public QueueCommand(MusicService musicService, GuildServiceProvider guildServices) {
+        super(guildServices);
+        this.musicService = musicService;
+    }
 
     @Override
     public boolean isEnabled() {
@@ -43,26 +60,26 @@ public class QueueCommand extends AbstractMusicCommand {
     @Override
     public void registerCommandOptions(CommandOptionsBuilder builder) {
         builder.addSubcommands(
-                new SubcommandData("clear-all", "Clear all queued tracks"),
+            new SubcommandData("clear-all", "Clear all queued tracks"),
-                new SubcommandData("delete-track", "Remove a single track from the queue")
+            new SubcommandData("delete-track", "Remove a single track from the queue")
-                        .addOptions(new OptionData(OptionType.INTEGER, "position", "Position of track", true)
+                .addOptions(new OptionData(OptionType.INTEGER, "position", "Position of track", true)
-                                .setMinValue(1)),
+                    .setMinValue(1)),
-                new SubcommandData("show-queue", "Display current queue"),
+            new SubcommandData("show-queue", "Display current queue"),
-                new SubcommandData("shuffle", "Shuffle the queue"),
+            new SubcommandData("shuffle", "Shuffle the queue"),
-                new SubcommandData("from-user", "View tracks added by a user")
+            new SubcommandData("from-user", "View tracks added by a user")
-                        .addOption(OptionType.USER, "user", "Which user?", true),
+                .addOption(OptionType.USER, "user", "Which user?", true),
-                new SubcommandData("remove-from-user", "Remove all tracks added by a user")
+            new SubcommandData("remove-from-user", "Remove all tracks added by a user")
-                        .addOption(OptionType.USER, "user", "Which user?", true)
+                .addOption(OptionType.USER, "user", "Which user?", true)
         );
     }
 
     @Override
     public CommandExecutionResult execute(CommandContext context) {
-        MusicManager manager = MusicManager.get(context.getGuild());
+        MusicManager manager = musicService.get(context.getGuild());
         String sub = context.getSubcommand();
         context.ack();
 
-        if (MusicUtils.checkIfConnected(context)) {
+        if (MusicUtils.checkIfConnected(context, manager)) {
 
             switch (sub) {
                 case "clear-all" -> {

src/main/java/me/bobert/netneutrality/command/music/ResumeCommand.java

@@ -4,14 +4,37 @@ package me.bobert.netneutrality.command.music;/*
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractMusicCommand;
+/*
+ * Copyright (c) anthorob
+ *
+ * https://discord.gg/qUa6zNFZsd
+ */
+
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.MusicCommand;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+import me.bobert.netneutrality.music.MusicService;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.music.MusicManager;
 import me.bobert.netneutrality.utils.MusicUtils;
 
-public class ResumeCommand extends AbstractMusicCommand {
+public class ResumeCommand extends MusicCommand {
+
+    private final MusicService musicService;
+
+    public ResumeCommand() {
+        this(null, null);
+    }
+
+    public ResumeCommand(MusicService musicService) {
+        this(musicService, null);
+    }
+
+    public ResumeCommand(MusicService musicService, GuildServiceProvider guildServices) {
+        super(guildServices);
+        this.musicService = musicService;
+    }
     @Override
     public boolean isEnabled() {
         return true;
@@ -34,9 +57,9 @@ public class ResumeCommand extends AbstractMusicCommand {
 
     @Override
     public CommandExecutionResult execute(CommandContext context) {
-        MusicManager manager = MusicManager.get(context.getGuild());
+        MusicManager manager = musicService.get(context.getGuild());
 
-        if (MusicUtils.checkIfConnected(context)) {
+        if (MusicUtils.checkIfConnected(context, manager)) {
             return manager.resume();
         }
 

src/main/java/me/bobert/netneutrality/command/music/ShuffleCommand.java

@@ -6,14 +6,31 @@ package me.bobert.netneutrality.command.music;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractMusicCommand;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.MusicCommand;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+import me.bobert.netneutrality.music.MusicService;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.music.MusicManager;
 import me.bobert.netneutrality.utils.MusicUtils;
 
-public class ShuffleCommand extends AbstractMusicCommand {
+public class ShuffleCommand extends MusicCommand {
+
+    private final MusicService musicService;
+
+    public ShuffleCommand() {
+        this(null, null);
+    }
+
+    public ShuffleCommand(MusicService musicService) {
+        this(musicService, null);
+    }
+
+    public ShuffleCommand(MusicService musicService, GuildServiceProvider guildServices) {
+        super(guildServices);
+        this.musicService = musicService;
+    }
     @Override
     public boolean isEnabled() {
         return true;
@@ -36,10 +53,10 @@ public class ShuffleCommand extends AbstractMusicCommand {
 
     @Override
     public CommandExecutionResult execute(CommandContext context) {
-        MusicManager manager = MusicManager.get(context.getGuild());
+        MusicManager manager = musicService.get(context.getGuild());
         context.ack();
 
-        if (MusicUtils.checkIfConnected(context)) {
+        if (MusicUtils.checkIfConnected(context, manager)) {
             return manager.getQueueManager().shuffle();
         }
 

src/main/java/me/bobert/netneutrality/command/music/SkipCommand.java

@@ -6,18 +6,35 @@ package me.bobert.netneutrality.command.music;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractMusicCommand;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.MusicCommand;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+import me.bobert.netneutrality.music.MusicService;
 import me.bobert.netneutrality.core.command.options.CommandOption;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.music.MusicManager;
 import me.bobert.netneutrality.utils.MusicUtils;
-import me.bobert.netneutrality.utils.UserFunction;
+import me.bobert.netneutrality.shared.util.UserFunction;
 import net.dv8tion.jda.api.interactions.commands.OptionType;
 import net.dv8tion.jda.api.interactions.commands.build.OptionData;
 
-public class SkipCommand extends AbstractMusicCommand {
+public class SkipCommand extends MusicCommand {
+
+    private final MusicService musicService;
+
+    public SkipCommand() {
+        this(null, null);
+    }
+
+    public SkipCommand(MusicService musicService) {
+        this(musicService, null);
+    }
+
+    public SkipCommand(MusicService musicService, GuildServiceProvider guildServices) {
+        super(guildServices);
+        this.musicService = musicService;
+    }
 
     @Override
     public boolean isEnabled() {
@@ -37,17 +54,17 @@ public class SkipCommand extends AbstractMusicCommand {
     @Override
     public void registerCommandOptions(CommandOptionsBuilder builder) {
         builder.addOptions(new OptionData(OptionType.INTEGER, "skip", "Number of tracks to skip")
-                .setMinValue(1));
+            .setMinValue(1));
     }
 
     @Override
     public CommandExecutionResult execute(CommandContext context) {
-        MusicManager manager = MusicManager.get(context.getGuild());
+        MusicManager manager = musicService.get(context.getGuild());
         context.ack();
 
-        if (MusicUtils.checkIfConnected(context)) {
+        if (MusicUtils.checkIfConnected(context, manager)) {
             int skips = context.getOption("skip", 1, CommandOption::getAsInt);
-            if (UserFunction.isAdmin(context) || MusicUtils.isUserDj(context)) {
+            if (UserFunction.isAdmin(context) || MusicUtils.isUserDj(context, manager)) {
                 return manager.getQueueManager().skip(skips);
             } else {
                 return manager.voteSkip(context);

src/main/java/me/bobert/netneutrality/command/music/StopCommand.java

@@ -6,15 +6,32 @@ package me.bobert.netneutrality.command.music;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractMusicCommand;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.MusicCommand;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+import me.bobert.netneutrality.music.MusicService;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.music.MusicManager;
 import me.bobert.netneutrality.utils.MusicUtils;
-import me.bobert.netneutrality.utils.UserFunction;
+import me.bobert.netneutrality.shared.util.UserFunction;
 
-public class StopCommand extends AbstractMusicCommand {
+public class StopCommand extends MusicCommand {
+
+    private final MusicService musicService;
+
+    public StopCommand() {
+        this(null, null);
+    }
+
+    public StopCommand(MusicService musicService) {
+        this(musicService, null);
+    }
+
+    public StopCommand(MusicService musicService, GuildServiceProvider guildServices) {
+        super(guildServices);
+        this.musicService = musicService;
+    }
 
     @Override
     public boolean isEnabled() {
@@ -38,10 +55,10 @@ public class StopCommand extends AbstractMusicCommand {
 
     @Override
     public CommandExecutionResult execute(CommandContext context) {
-        MusicManager manager = MusicManager.get(context.getGuild());
+        MusicManager manager = musicService.get(context.getGuild());
         context.ack();
 
-        if (MusicUtils.checkIfConnected(context)) {
+        if (MusicUtils.checkIfConnected(context, manager)) {
             if (UserFunction.isAdmin(context)) {
                 manager.stopTrack();
                 context.reply("Stopping current track");

src/main/java/me/bobert/netneutrality/command/music/ViewQueueCommand.java

@@ -5,15 +5,32 @@ package me.bobert.netneutrality.command.music;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractMusicCommand;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.MusicCommand;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+import me.bobert.netneutrality.music.MusicService;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.music.MusicManager;
-import me.bobert.netneutrality.utils.MessageFunction;
+import me.bobert.netneutrality.shared.util.MessageFunction;
 import me.bobert.netneutrality.utils.MusicUtils;
 
-public class ViewQueueCommand extends AbstractMusicCommand {
+public class ViewQueueCommand extends MusicCommand {
+
+    private final MusicService musicService;
+
+    public ViewQueueCommand() {
+        this(null, null);
+    }
+
+    public ViewQueueCommand(MusicService musicService) {
+        this(musicService, null);
+    }
+
+    public ViewQueueCommand(MusicService musicService, GuildServiceProvider guildServices) {
+        super(guildServices);
+        this.musicService = musicService;
+    }
 
     @Override
     public boolean isEnabled() {
@@ -37,10 +54,10 @@ public class ViewQueueCommand extends AbstractMusicCommand {
 
     @Override
     public CommandExecutionResult execute(CommandContext context) {
-        MusicManager manager = MusicManager.get(context.getGuild());
+        MusicManager manager = musicService.get(context.getGuild());
         context.ack();
 
-        if (MusicUtils.checkIfConnected(context)) {
+        if (MusicUtils.checkIfConnected(context, manager)) {
             int queueSize = manager.getQueueSize();
             if (queueSize == 0) {
                 return CommandExecutionResult.warn("Queue is empty!");

src/main/java/me/bobert/netneutrality/command/music/VolumeCommand.java

@@ -6,18 +6,35 @@ package me.bobert.netneutrality.command.music;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractMusicCommand;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.MusicCommand;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+import me.bobert.netneutrality.music.MusicService;
 import me.bobert.netneutrality.core.command.options.CommandOption;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.music.MusicManager;
 import me.bobert.netneutrality.utils.MusicUtils;
-import me.bobert.netneutrality.utils.UserFunction;
+import me.bobert.netneutrality.shared.util.UserFunction;
 import net.dv8tion.jda.api.interactions.commands.OptionType;
 import net.dv8tion.jda.api.interactions.commands.build.OptionData;
 
-public class VolumeCommand extends AbstractMusicCommand {
+public class VolumeCommand extends MusicCommand {
+
+    private final MusicService musicService;
+
+    public VolumeCommand() {
+        this(null, null);
+    }
+
+    public VolumeCommand(MusicService musicService) {
+        this(musicService, null);
+    }
+
+    public VolumeCommand(MusicService musicService, GuildServiceProvider guildServices) {
+        super(guildServices);
+        this.musicService = musicService;
+    }
 
     @Override
     public boolean isEnabled() {
@@ -37,16 +54,16 @@ public class VolumeCommand extends AbstractMusicCommand {
     @Override
     public void registerCommandOptions(CommandOptionsBuilder builder) {
         builder.addOptions(new OptionData(OptionType.INTEGER, "volume", "Playback volume for this session", true)
-                .setRequiredRange(0, 100));
+            .setRequiredRange(0, 100));
     }
 
     @Override
     public CommandExecutionResult execute(CommandContext context) {
-        MusicManager manager = MusicManager.get(context.getGuild());
+        MusicManager manager = musicService.get(context.getGuild());
         int volume = context.getOption("volume", 30, CommandOption::getAsInt);
 
-        if (MusicUtils.checkIfConnected(context)) {
+        if (MusicUtils.checkIfConnected(context, manager)) {
-            if (UserFunction.isAdmin(context) || MusicUtils.isUserDj(context)) {
+            if (UserFunction.isAdmin(context) || MusicUtils.isUserDj(context, manager)) {
                 manager.setVolume(volume);
                 return CommandExecutionResult.success(String.format("Volume set to %s", volume));
             }

src/main/java/me/bobert/netneutrality/command/music/VoteSkipCommand.java

@@ -5,14 +5,31 @@ package me.bobert.netneutrality.command.music;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractMusicCommand;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.impl.MusicCommand;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+import me.bobert.netneutrality.music.MusicService;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.music.MusicManager;
 import me.bobert.netneutrality.utils.MusicUtils;
 
-public class VoteSkipCommand extends AbstractMusicCommand {
+public class VoteSkipCommand extends MusicCommand {
+
+    private final MusicService musicService;
+
+    public VoteSkipCommand() {
+        this(null, null);
+    }
+
+    public VoteSkipCommand(MusicService musicService) {
+        this(musicService, null);
+    }
+
+    public VoteSkipCommand(MusicService musicService, GuildServiceProvider guildServices) {
+        super(guildServices);
+        this.musicService = musicService;
+    }
 
     @Override
     public boolean isEnabled() {
@@ -36,9 +53,9 @@ public class VoteSkipCommand extends AbstractMusicCommand {
 
     @Override
     public CommandExecutionResult execute(CommandContext context) {
-        MusicManager manager = MusicManager.get(context.getGuild());
+        MusicManager manager = musicService.get(context.getGuild());
 
-        if (MusicUtils.checkIfConnected(context)) {
+        if (MusicUtils.checkIfConnected(context, manager)) {
             return manager.voteSkip(context);
         }
 

src/main/java/me/bobert/netneutrality/command/react/CreateEmojiReaction.java

@@ -6,25 +6,35 @@ package me.bobert.netneutrality.command.react;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractMessageMenuCommand;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
+import me.bobert.netneutrality.core.command.impl.MessageMenuCommand;
 import me.bobert.netneutrality.core.context.CommandContext;
-import me.bobert.netneutrality.core.tasks.TaskManager;
+import me.bobert.netneutrality.tasks.reaction.EmojiReactionRoleTask;
-import me.bobert.netneutrality.tasks.emoji.EmojiReactionRoleTask;
 import me.bobert.netneutrality.tasks.reaction.EmojiRoleFirstStep;
 import net.dv8tion.jda.api.entities.Message;
+import me.bobert.netneutrality.core.tasks.TaskManager;
+
+import java.util.Objects;
+
+public class CreateEmojiReaction extends MessageMenuCommand {
+
+    private final TaskManager taskManager;
+
+    public CreateEmojiReaction(TaskManager taskManager) {
+        Objects.requireNonNull(taskManager, "TaskManager must not be null");
+        this.taskManager = taskManager;
+    }
 
-public class CreateEmojiReaction extends AbstractMessageMenuCommand {
     @Override
     public CommandExecutionResult execute(Message target, CommandContext context) {
-        EmojiReactionRoleTask task = TaskManager.getInstance().findTaskByPartialId(EmojiReactionRoleTask.class, target.getId()).orElse(null);
+        EmojiReactionRoleTask task = taskManager.findTaskByPartialId(EmojiReactionRoleTask.class, target.getId()).orElse(null);
 
         if (task != null) {
             context.replyEphemeral("This message is already registered with the bot, please use the modify command instead");
             return CommandExecutionResult.none();
         }
 
-        return CommandExecutionResult.task(new EmojiRoleFirstStep(target));
+        return CommandExecutionResult.task(new EmojiRoleFirstStep(taskManager, target));
     }
 
     @Override

src/main/java/me/bobert/netneutrality/command/react/ModifyEmojiReaction.java

@@ -6,25 +6,35 @@ package me.bobert.netneutrality.command.react;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.AbstractMessageMenuCommand;
 import me.bobert.netneutrality.core.command.CommandExecutionResult;
+import me.bobert.netneutrality.core.command.impl.MessageMenuCommand;
 import me.bobert.netneutrality.core.context.CommandContext;
-import me.bobert.netneutrality.core.tasks.TaskManager;
+import me.bobert.netneutrality.tasks.reaction.EmojiReactionRoleTask;
-import me.bobert.netneutrality.tasks.emoji.EmojiReactionRoleTask;
 import me.bobert.netneutrality.tasks.reaction.EmojiRoleModify;
 import net.dv8tion.jda.api.entities.Message;
+import me.bobert.netneutrality.core.tasks.TaskManager;
+
+import java.util.Objects;
+
+public class ModifyEmojiReaction extends MessageMenuCommand {
+
+    private final TaskManager taskManager;
+
+    public ModifyEmojiReaction(TaskManager taskManager) {
+        Objects.requireNonNull(taskManager, "TaskManager must not be null");
+        this.taskManager = taskManager;
+    }
 
-public class ModifyEmojiReaction extends AbstractMessageMenuCommand {
 
     @Override
     public CommandExecutionResult execute(Message target, CommandContext context) {
-        EmojiReactionRoleTask task = TaskManager.getInstance().findTaskByPartialId(EmojiReactionRoleTask.class, target.getId()).orElse(null);
+        EmojiReactionRoleTask task = taskManager.findTaskByPartialId(EmojiReactionRoleTask.class, target.getId()).orElse(null);
         if (task == null) {
             context.replyEphemeral("This message is not registered with the bot, please use the create command instead");
             return CommandExecutionResult.none();
         }
 
-        return CommandExecutionResult.task(new EmojiRoleModify(target, task));
+        return CommandExecutionResult.task(new EmojiRoleModify(taskManager, target, task));
     }
 
     @Override

src/main/java/me/bobert/netneutrality/context/MusicChannelContext.java

@@ -6,11 +6,12 @@ package me.bobert.netneutrality.context;
  */
 
 import me.bobert.netneutrality.core.context.AbstractContext;
+import me.bobert.netneutrality.core.context.AsyncContext;
 import me.bobert.netneutrality.core.context.NoMessageContext;
+import net.dv8tion.jda.api.components.MessageTopLevelComponent;
 import net.dv8tion.jda.api.entities.Member;
 import net.dv8tion.jda.api.entities.channel.middleman.GuildMessageChannel;
 import net.dv8tion.jda.api.events.Event;
-import net.dv8tion.jda.api.interactions.components.LayoutComponent;
 import net.dv8tion.jda.api.utils.messages.MessageCreateData;
 
 import java.util.List;
@@ -43,7 +44,7 @@ public class MusicChannelContext extends AbstractContext implements NoMessageCon
     }
 
     @Override
-    public void reply(MessageCreateData messageCreateData, boolean ephemeral, List<LayoutComponent> components, Consumer<AsyncContext> consumer) {
+    public void reply(MessageCreateData messageCreateData, boolean ephemeral, List<MessageTopLevelComponent> components, Consumer<AsyncContext> consumer) {
         if (getChannel().canTalk()) {
             getChannel().sendMessage(messageCreateData).setComponents(components).queue(message -> consumer.accept(new AsyncContext(message)));
         }

src/main/java/me/bobert/netneutrality/context/command/MessageCommandContext.java

@@ -9,8 +9,11 @@ import me.bobert.netneutrality.core.command.options.CommandOption;
 import me.bobert.netneutrality.core.command.options.MessageCommandOption;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.core.context.MessageContext;
-import me.bobert.netneutrality.utils.Settings;
+import me.bobert.netneutrality.utils.SettingsProvider;
-import net.dv8tion.jda.api.entities.*;
+import net.dv8tion.jda.api.entities.Member;
+import net.dv8tion.jda.api.entities.Mentions;
+import net.dv8tion.jda.api.entities.Message;
+import net.dv8tion.jda.api.entities.Role;
 import net.dv8tion.jda.api.entities.channel.ChannelType;
 import net.dv8tion.jda.api.entities.channel.middleman.GuildChannel;
 import net.dv8tion.jda.api.events.message.MessageReceivedEvent;
@@ -27,8 +30,11 @@ public class MessageCommandContext extends CommandContext implements MessageCont
     private final MessageReceivedEvent event;
     private final Message message;
 
-    public MessageCommandContext(MessageReceivedEvent event) {
+    private final SettingsProvider settings;
-        super(event.getJDA(), event.isFromGuild() ? event.getGuild() : null, event.getChannel(), event.getMember(), event.getAuthor());
+
+    public MessageCommandContext(MessageReceivedEvent event, SettingsProvider settings) {
+        super(event.getJDA(), event.isFromGuild() ? event.getGuild() : null, event.getChannel(), event.getMember(), event.getAuthor(), settings);
+        this.settings = settings;
         this.event = event;
         this.message = event.getMessage();
     }
@@ -41,10 +47,10 @@ public class MessageCommandContext extends CommandContext implements MessageCont
     @Override
     public String getId() {
         return String.format("%s:%s:%s:%s",
-                getGuild() == null ? "PrivateMessage" : getGuild().getId(),
+            getGuild() == null ? "PrivateMessage" : getGuild().getId(),
-                getChannel().getId(),
+            getChannel().getId(),
-                getDiscordUser().getId(),
+            getDiscordUser().getId(),
-                message.getId());
+            message.getId());
     }
 
     @Override
@@ -55,6 +61,7 @@ public class MessageCommandContext extends CommandContext implements MessageCont
     @Override
     public List<CommandOption> parseOptions(String[] args, List<OptionData> commandOptions) {
         List<CommandOption> options = new ArrayList<>();
+        int required = commandOptions.stream().filter(OptionData::isRequired).toList().size();
         Mentions mentions = message.getMentions();
         int roleMentionIndex = 0;
         int userMentionIndex = 0;
@@ -71,13 +78,59 @@ public class MessageCommandContext extends CommandContext implements MessageCont
             try {
                 switch (type) {
                     case STRING -> {
-                        String str = args[index];
+                        int currentOptionIndex = commandOptions.indexOf(data);
+                        boolean nextOptionIsString = false;
+                        if (currentOptionIndex + 1 < commandOptions.size()) {
+                            OptionData nextOption = commandOptions.get(currentOptionIndex + 1);
+                            nextOptionIsString = nextOption.getType() == OptionType.STRING;
+                        }
 
-                        if ((str.contains("<@") || str.contains("<#")) && str.contains(">")) {
+                        StringBuilder strBuilder = new StringBuilder();
-                            invalidateContext(data, "expected a string at position " + (index + 1) + " but a role/user/channel was provided");
+                        if (!nextOptionIsString) {
+                            while (index < args.length) {
+                                String nextArg = args[index];
+
+                                if ((nextArg.contains("<@") || nextArg.contains("<#") || nextArg.contains("<@&")) && nextArg.contains(">")) {
+                                    break;
+                                }
+
+                                if (nextArg.equalsIgnoreCase("true") || nextArg.equalsIgnoreCase("false")) {
+                                    break;
+                                }
+
+                                try {
+                                    Long.parseLong(nextArg);
+                                    break;
+                                } catch (NumberFormatException ignored) {}
+
+                                try {
+                                    Double.parseDouble(nextArg);
+                                    break;
+                                } catch (NumberFormatException ignored) {}
+
+                                if (!strBuilder.isEmpty()) {
+                                    strBuilder.append(" ");
+                                }
+
+                                strBuilder.append(nextArg);
+                                index++;
+                            }
+
+                            // Update index to skip the concatenated strings
+                            index = index - 1;
+                        } else {
+                            // Next option is also a string, so just take the current argument
+                            if (index < args.length) {
+                                strBuilder.append(args[index]);
+                            }
+                        }
+
+                        if (strBuilder.isEmpty()) {
                             break;
                         }
 
+                        String str = strBuilder.toString();
+
                         if (!choices.isEmpty()) {
                             List<Command.Choice> matched = choices.stream().filter(choice -> choice.getAsString().equalsIgnoreCase(str)).toList();
                             if (matched.isEmpty()) {
@@ -116,8 +169,6 @@ public class MessageCommandContext extends CommandContext implements MessageCont
                         } else if (max != null && num > max.longValue()) {
                             value = max.longValue();
                         }
-
-                        value = num;
                     }
                     case BOOLEAN -> {
                         String str = args[index];
@@ -129,7 +180,7 @@ public class MessageCommandContext extends CommandContext implements MessageCont
                         invalidateContext(data, "expected true or false");
                     }
                     case NUMBER -> {
-                        double num = Long.parseLong(args[index]);
+                        double num = Double.parseDouble(args[index]);
                         if (!choices.isEmpty()) {
                             List<Command.Choice> matched = choices.stream().filter(choice -> choice.getAsDouble() == num).toList();
                             if (matched.isEmpty()) {
@@ -206,9 +257,9 @@ public class MessageCommandContext extends CommandContext implements MessageCont
                         if (mentions.getChannels().size() > channelMentionIndex) {
                             GuildChannel channel = mentions.getChannels().get(channelMentionIndex++);
 
-                            if (!requiredChannelTypes.contains(channel.getType())) {
+                            if (!requiredChannelTypes.isEmpty() && !requiredChannelTypes.contains(channel.getType())) {
                                 invalidateContext(data, "not a valid channel type at index " + (index + 1) +
-                                        " , valid types are: " + validTypes(requiredChannelTypes));
+                                    " , valid types are: " + validTypes(requiredChannelTypes));
                                 break;
                             }
 
@@ -222,7 +273,11 @@ public class MessageCommandContext extends CommandContext implements MessageCont
                     }
                 }
             } catch (IndexOutOfBoundsException e) {
-                if (data.isRequired()) {
+                if (options.size() < required) {
+                    invalidateContext(data, "missing required argument at index " + (index + 1));
+                }
+
+                if (data.isRequired() && index < required) {
                     // This should never happen because required options are validated before calling parseOptions()
                     throw new IllegalArgumentException("Required option " + data.getName() + " was not found at index " + index);
                 }
@@ -237,6 +292,13 @@ public class MessageCommandContext extends CommandContext implements MessageCont
             index++;
         }
 
+        // Check if there are leftover arguments that weren't consumed
+        if (index < args.length) {
+            if (options.size() >= required) {
+                invalidateContext(commandOptions.getLast(), "too many arguments");
+            }
+        }
+
         return options;
     }
 
@@ -261,7 +323,7 @@ public class MessageCommandContext extends CommandContext implements MessageCont
     @Override
     public String parseCommandName() {
         String rawMessage = message.getContentRaw().trim();
-        String prefix = Settings.getInstance().getPrefix();
+        String prefix = settings.getPrefix();
 
         if (rawMessage.startsWith(prefix)) {
             return getFullCommand().split(" ", 2)[0];
@@ -273,7 +335,7 @@ public class MessageCommandContext extends CommandContext implements MessageCont
     @Override
     public String getFullCommand() {
         String rawMessage = message.getContentRaw().trim();
-        String prefix = Settings.getInstance().getPrefix();
+        String prefix = settings.getPrefix();
 
         return rawMessage.replaceFirst("^[" + prefix + "\\s]+", "").trim();
     }

src/main/java/me/bobert/netneutrality/context/command/MessageMenuContext.java

@@ -9,6 +9,7 @@ package me.bobert.netneutrality.context.command;
 import me.bobert.netneutrality.core.command.options.CommandOption;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.core.context.InteractionContext;
+import me.bobert.netneutrality.utils.SettingsProvider;
 import net.dv8tion.jda.api.entities.Message;
 import net.dv8tion.jda.api.entities.channel.ChannelType;
 import net.dv8tion.jda.api.events.Event;
@@ -20,8 +21,13 @@ import java.util.List;
 public class MessageMenuContext extends CommandContext implements InteractionContext {
     private final MessageContextInteractionEvent event;
 
-    public MessageMenuContext(MessageContextInteractionEvent event) {
+    @Override
-        super(event.getJDA(), event.getGuild(), event.getChannel(), event.getMember(), event.getUser());
+    public boolean isInteraction() {
+        return true;
+    }
+
+    public MessageMenuContext(MessageContextInteractionEvent event, SettingsProvider settings) {
+        super(event.getJDA(), event.getGuild(), event.getChannel(), event.getMember(), event.getUser(), settings);
         this.event = event;
     }
 

src/main/java/me/bobert/netneutrality/context/command/SlashCommandContext.java

@@ -9,6 +9,7 @@ import me.bobert.netneutrality.core.command.options.CommandOption;
 import me.bobert.netneutrality.core.command.options.SlashCommandOption;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.core.context.InteractionContext;
+import me.bobert.netneutrality.utils.SettingsProvider;
 import net.dv8tion.jda.api.entities.channel.ChannelType;
 import net.dv8tion.jda.api.events.interaction.command.SlashCommandInteractionEvent;
 import net.dv8tion.jda.api.interactions.commands.build.OptionData;
@@ -19,11 +20,21 @@ import java.util.stream.Collectors;
 public class SlashCommandContext extends CommandContext implements InteractionContext {
     private final SlashCommandInteractionEvent event;
 
-    public SlashCommandContext(SlashCommandInteractionEvent event) {
+    public SlashCommandContext(SlashCommandInteractionEvent event, SettingsProvider settings) {
-        super(event.getJDA(), event.getGuild(), event.getChannel(), event.getMember(), event.getUser());
+        super(event.getJDA(), event.getGuild(), event.getChannel(), event.getMember(), event.getUser(), settings);
         this.event = event;
     }
 
+    @Override
+    public boolean isInteraction() {
+        return true;
+    }
+
+    @Override
+    public boolean canSkipPermissionCheck() {
+        return true;
+    }
+
     @Override
     public SlashCommandInteractionEvent getEvent() {
         return event;

src/main/java/me/bobert/netneutrality/context/command/UserMenuContext.java

@@ -9,6 +9,7 @@ package me.bobert.netneutrality.context.command;
 import me.bobert.netneutrality.core.command.options.CommandOption;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.core.context.InteractionContext;
+import me.bobert.netneutrality.utils.SettingsProvider;
 import net.dv8tion.jda.api.entities.User;
 import net.dv8tion.jda.api.entities.channel.ChannelType;
 import net.dv8tion.jda.api.entities.channel.middleman.MessageChannel;
@@ -21,8 +22,13 @@ import java.util.List;
 public class UserMenuContext extends CommandContext implements InteractionContext {
     private final UserContextInteractionEvent event;
 
-    public UserMenuContext(UserContextInteractionEvent event) {
+    @Override
-        super(event.getJDA(), event.getGuild(), (MessageChannel) event.getChannel(), event.getMember(), event.getUser());
+    public boolean isInteraction() {
+        return true;
+    }
+
+    public UserMenuContext(UserContextInteractionEvent event, SettingsProvider settings) {
+        super(event.getJDA(), event.getGuild(), (MessageChannel) event.getChannel(), event.getMember(), event.getUser(), settings);
         this.event = event;
     }
 

src/main/java/me/bobert/netneutrality/context/tasks/EmojiTaskContext.java

@@ -5,14 +5,11 @@ package me.bobert.netneutrality.context.tasks;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.context.AsyncContext;
+import me.bobert.netneutrality.core.context.AsyncContext;
 import me.bobert.netneutrality.core.context.NoMessageContext;
 import me.bobert.netneutrality.core.context.TaskContext;
-import net.dv8tion.jda.api.entities.channel.ChannelType;
+import net.dv8tion.jda.api.components.MessageTopLevelComponent;
 import net.dv8tion.jda.api.events.message.react.MessageReactionAddEvent;
-import net.dv8tion.jda.api.interactions.InteractionHook;
-import net.dv8tion.jda.api.interactions.components.LayoutComponent;
-import net.dv8tion.jda.api.interactions.modals.Modal;
 import net.dv8tion.jda.api.utils.messages.MessageCreateData;
 
 import java.util.List;
@@ -45,7 +42,7 @@ public class EmojiTaskContext extends TaskContext implements NoMessageContext {
     }
 
     @Override
-    public void reply(MessageCreateData messageCreateData, boolean ephemeral, List<LayoutComponent> components, Consumer<AsyncContext> consumer) {
+    public void reply(MessageCreateData messageCreateData, boolean ephemeral, List<MessageTopLevelComponent> components, Consumer<AsyncContext> consumer) {
         if (getChannel() != null && getChannel().canTalk()) {
             getChannel().sendMessage(messageCreateData).setComponents(components).queue(message -> consumer.accept(new AsyncContext(message)));
         }

src/main/java/me/bobert/netneutrality/core/LogHandler.java

@@ -9,9 +9,9 @@ import io.sentry.Sentry;
 import me.bobert.netneutrality.core.context.CommandContext;
 import me.bobert.netneutrality.core.context.Context;
 import me.bobert.netneutrality.core.context.TaskContext;
-import me.bobert.netneutrality.db.service.GuildService;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
 import me.bobert.netneutrality.exceptions.ContextException;
-import me.bobert.netneutrality.utils.MessageFunction;
+import me.bobert.netneutrality.shared.util.MessageFunction;
 import net.dv8tion.jda.api.entities.Guild;
 import net.dv8tion.jda.api.entities.channel.concrete.TextChannel;
 import org.apache.logging.log4j.LogManager;
@@ -20,6 +20,17 @@ import org.apache.logging.log4j.Logger;
 public class LogHandler {
 
     private static final Logger logger = LogManager.getLogger(LogHandler.class);
+    private static volatile GuildServiceProvider guildServices;
+
+    /**
+     * Binds the guild-service provider used for debug-channel logging. Called once during bootstrap.
+     *
+     * @param provider the live guild service provider
+     */
+    public static void bind(GuildServiceProvider provider) {
+        guildServices = provider;
+    }
+
 
     /**
      * Log an exception accordingly
@@ -51,10 +62,10 @@ public class LogHandler {
 
     public static void sendMessageToDebugChannel(Guild guild, String message) {
         guild.getTextChannels()
-                .stream()
+            .stream()
-                .filter(textChannel -> textChannel.getName().equals("debug") || textChannel.getName().equals("log"))
+            .filter(textChannel -> textChannel.getName().equals("debug") || textChannel.getName().equals("log"))
-                .filter(TextChannel::canTalk)
+            .filter(TextChannel::canTalk)
-                .forEach(textChannel -> textChannel.sendMessage(message).queue());
+            .forEach(textChannel -> textChannel.sendMessage(message).queue());
 
     }
 
@@ -63,8 +74,8 @@ public class LogHandler {
         String guildId = context.getGuild() == null ? "PrivateMessage" : context.getGuild().getId();
 
         logger.error("Exception thrown from context (guild: {}, user: {}): {}", guildId,
-                context.getDiscordUser().getId(),
+            context.getDiscordUser().getId(),
-                exception.getMessage()
+            exception.getMessage()
         );
 
         if (context instanceof CommandContext commandContext) {
@@ -80,13 +91,14 @@ public class LogHandler {
         Context context = exception.getContext();
 
         if (context.getGuild() != null) {
-            if (GuildService.get(context.getGuild()).isDebugEnabled()) {
+            GuildServiceProvider provider = guildServices;
+            if (provider != null && provider.get(context.getGuild()).isDebugEnabled()) {
                 context.getGuild()
-                        .getTextChannels()
+                    .getTextChannels()
-                        .stream()
+                    .stream()
-                        .filter(textChannel -> textChannel.getName().equals("debug") || textChannel.getName().equals("log"))
+                    .filter(textChannel -> textChannel.getName().equals("debug") || textChannel.getName().equals("log"))
-                        .filter(TextChannel::canTalk)
+                    .filter(TextChannel::canTalk)
-                        .forEach(textChannel -> textChannel.sendMessageEmbeds(MessageFunction.buildDebugMessage(exception)).queue());
+                    .forEach(textChannel -> textChannel.sendMessageEmbeds(MessageFunction.buildDebugMessage(exception)).queue());
             }
         }
     }

src/main/java/me/bobert/netneutrality/core/NetNeutralityBot.java

@@ -0,0 +1,20 @@
+package me.bobert.netneutrality.core;
+
+/*
+ * Copyright (c) anthorob
+ *
+ * https://discord.gg/qUa6zNFZsd
+ */
+
+import me.bobert.netneutrality.bootstrap.Lifecycle;
+
+public class NetNeutralityBot implements Lifecycle {
+    @Override
+    public void start() throws Exception {
+    }
+
+    @Override
+    public int priority() {
+        return 0;
+    }
+}

src/main/java/me/bobert/netneutrality/core/command/AbstractMusicCommand.java

@@ -1,77 +0,0 @@
-package me.bobert.netneutrality.core.command;
-/*
- * Copyright (c) anthorob
- *
- * https://discord.gg/qUa6zNFZsd
- */
-
-import me.bobert.netneutrality.db.GSettings;
-import me.bobert.netneutrality.db.service.GuildService;
-import me.bobert.netneutrality.utils.UserFunction;
-import net.dv8tion.jda.api.entities.Guild;
-import net.dv8tion.jda.api.entities.Member;
-import net.dv8tion.jda.api.entities.Role;
-import net.dv8tion.jda.api.entities.channel.ChannelType;
-import net.dv8tion.jda.api.entities.channel.middleman.GuildMessageChannel;
-import net.dv8tion.jda.api.entities.channel.middleman.MessageChannel;
-
-public abstract class AbstractMusicCommand extends AbstractCommand {
-
-    @Override
-    public boolean needAdmin() {
-        return false;
-    }
-
-    @Override
-    public boolean isGuildOnly() {
-        return true;
-    }
-
-    @Override
-    public CommandCategory getCategory() {
-        return CommandCategory.MUSIC;
-    }
-
-    @Override
-    public boolean canBeExecutedBy(Member member) {
-        if (member == null) {
-            return true;
-        }
-
-        Guild guild = member.getGuild();
-
-        String roleDb = GuildService.get(guild.getId()).getGuildSettingService().getSetting(GSettings.MUSIC_ROLE);
-
-        if (roleDb != null && !roleDb.isEmpty()) {
-            if (UserFunction.isAdmin(member)) {
-                return true;
-            }
-
-            Role neededRole = guild.getRoleById(roleDb);
-            if (neededRole == null) {
-                // Role doesn't exist on guild anymore, remove from db
-                GuildService.get(guild.getId()).getGuildSettingService().setSettingValue(GSettings.MUSIC_ROLE, null);
-                return true;
-            }
-
-            return member.getRoles().contains(neededRole);
-        }
-
-        return true;
-    }
-
-    @Override
-    public boolean canBeExecutedFrom(MessageChannel channel) {
-        if (channel instanceof GuildMessageChannel guildMessageChannel) {
-            if (channel.getType() != ChannelType.TEXT)
-                return false;
-
-            String channelDb = GuildService.get(guildMessageChannel.getGuild()).getGuildSettingService().getSetting(GSettings.MUSIC_CHANNEL);
-            if (channelDb != null && !channelDb.isEmpty()) {
-                return channelDb.equals(channel.getId());
-            }
-        }
-
-        return true;
-    }
-}

src/main/java/me/bobert/netneutrality/core/command/Command.java

@@ -5,7 +5,6 @@ package me.bobert.netneutrality.core.command;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
 import me.bobert.netneutrality.core.context.CommandContext;
 import net.dv8tion.jda.api.entities.Member;
 import net.dv8tion.jda.api.entities.channel.middleman.MessageChannel;

src/main/java/me/bobert/netneutrality/core/command/CommandContainer.java

@@ -5,35 +5,178 @@ package me.bobert.netneutrality.core.command;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.options.CommandOptions;
+import net.dv8tion.jda.api.entities.channel.ChannelType;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
+import net.dv8tion.jda.api.interactions.commands.build.OptionData;
+import net.dv8tion.jda.api.interactions.commands.build.SlashCommandData;
+import net.dv8tion.jda.api.interactions.commands.build.SubcommandData;
+import net.dv8tion.jda.api.interactions.commands.build.SubcommandGroupData;
+import net.dv8tion.jda.internal.interactions.CommandDataImpl;
+
+import java.util.List;
+import java.util.Set;
+import java.util.StringJoiner;
 
 public class CommandContainer {
     public static final CommandContainer NULL_COMMAND = new CommandContainer(null);
     private final Command command;
-    private CommandOptions commandOptions;
+    private CommandDataImpl commandData;
+    private List<OptionData> options;
+    private List<SubcommandData> subcommands;
+    private List<SubcommandGroupData> subcommandGroups;
 
     public CommandContainer(Command command) {
         this.command = command;
+
+        if (command != null) {
+            CommandOptionsBuilder commandOptionsBuilder = new CommandOptionsBuilder(command.getType(), command);
+            command.registerCommandOptions(commandOptionsBuilder);
+            initContainer(commandOptionsBuilder);
+        }
     }
 
     public Command getCommand() {
         return command;
     }
 
-    public CommandOptions getCommandOptions() {
+    public SlashCommandData getSlashCommandData() {
-        return commandOptions;
+        return commandData;
     }
 
-    public void init() {
+    public List<OptionData> getOptions() {
-        initOptions();
+        return options;
     }
 
-    private void initOptions() {
+    public List<SubcommandData> getSubcommands() {
-        if (command != null) {
+        return subcommands;
-            CommandOptionsBuilder commandOptionsBuilder = new CommandOptionsBuilder(command.getType(), command);
+    }
-            command.registerCommandOptions(commandOptionsBuilder);
+
-            commandOptions = commandOptionsBuilder.build();
+    public List<SubcommandGroupData> getSubcommandGroups() {
+        return subcommandGroups;
+    }
+
+    private void initContainer(CommandOptionsBuilder builder) {
+        this.commandData = builder.build();
+        this.options = commandData.getOptions();
+        this.subcommands = commandData.getSubcommands();
+        this.subcommandGroups = commandData.getSubcommandGroups();
+    }
+
+    public boolean isEmpty() {
+        return options.isEmpty() && subcommands.isEmpty() && subcommandGroups.isEmpty();
+    }
+
+    public String printUsage() {
+        StringBuilder usage = new StringBuilder();
+        if (!options.isEmpty()) {
+            usage.append("- Usage: /").append(command.getCommandName());
+            for (OptionData option : options) {
+                usage.append(" <").append(option.getName()).append(">");
+            }
+
+            usage.append(printOptions(options, null, false));
         }
+
+        if (!subcommands.isEmpty()) {
+            for (SubcommandData subcommand : subcommands) {
+                usage.append("- Usage: /").append(command.getCommandName()).append(" ").append(subcommand.getName());
+
+                for (OptionData option : subcommand.getOptions()) {
+                    usage.append(" <").append(option.getName()).append(">");
+                }
+
+                usage.append(" (").append(subcommand.getDescription()).append(")");
+                usage.append(printOptions(subcommand.getOptions(), null, false));
+
+                usage.append("\n");
+            }
+        }
+
+        if (!subcommandGroups.isEmpty()) {
+            for (SubcommandGroupData subcommandGroup : subcommandGroups) {
+                usage.append("- Subcommand: /").append(command.getCommandName())
+                    .append(" ").append(subcommandGroup.getName())
+                    .append(" (").append(subcommandGroup.getDescription()).append(")")
+                    .append("\n");
+
+                for (SubcommandData subcommand : subcommandGroup.getSubcommands()) {
+                    usage.append("  - Usage: /").append(command.getCommandName())
+                        .append(" ").append(subcommandGroup.getName())
+                        .append(" ").append(subcommand.getName());
+
+                    for (OptionData option : subcommand.getOptions()) {
+                        usage.append(" <").append(option.getName()).append(">");
+                    }
+
+                    usage.append(printOptions(subcommand.getOptions(), subcommand.getDescription(), true));
+
+                    usage.append("\n");
+                }
+            }
+        }
+
+        if (!isEmpty()) {
+            usage.append("\n\n-# *: required argument");
+        }
+
+        return usage.toString();
+    }
+
+    private String printOptions(List<OptionData> options, String description, boolean group) {
+        StringBuilder usage = new StringBuilder();
+
+        if (description != null) {
+            usage.append(" (").append(description).append(")");
+        }
+
+        for (OptionData option : options) {
+            usage.append("\n");
+            if (group) {
+                usage.append("  ");
+            }
+
+            usage.append("  - ");
+            if (option.isRequired()) {
+                usage.append("*");
+            }
+            usage.append(option.getName()).append(": ").append(option.getDescription());
+
+            if (option.getMinValue() != null) {
+                usage.append(" [Min value: ").append(option.getMinValue().longValue()).append("]");
+            }
+
+            if (option.getMaxValue() != null) {
+                usage.append(" [Max value: ").append(option.getMaxValue().longValue()).append("]");
+            }
+
+            if (option.getMinLength() != null) {
+                usage.append(" [Min length: ").append(option.getMinLength().longValue()).append("]");
+            }
+
+            if (option.getMaxLength() != null) {
+                usage.append(" [Max length: ").append(option.getMaxLength().longValue()).append("]");
+            }
+
+            List<net.dv8tion.jda.api.interactions.commands.Command.Choice> choices = option.getChoices();
+            if (!choices.isEmpty()) {
+                StringJoiner joiner = new StringJoiner(", ");
+                for (net.dv8tion.jda.api.interactions.commands.Command.Choice choice : choices) {
+                    joiner.add(choice.getAsString());
+                }
+
+                usage.append(" [Available choices: ").append(joiner).append("]");
+            }
+
+            Set<ChannelType> requiredChannelTypes = option.getChannelTypes();
+            if (!requiredChannelTypes.isEmpty()) {
+                StringJoiner joiner = new StringJoiner(", ");
+                for (ChannelType type : requiredChannelTypes) {
+                    joiner.add(type.name());
+                }
+
+                usage.append(" [Required channel types: ").append(joiner).append("]");
+            }
+        }
+
+        return usage.toString();
     }
 }

src/main/java/me/bobert/netneutrality/core/command/CommandManager.java

@@ -5,24 +5,56 @@ package me.bobert.netneutrality.core.command;
  * https://discord.gg/qUa6zNFZsd
  */
 
+import me.bobert.netneutrality.bootstrap.ApplicationContext;
+import me.bobert.netneutrality.bootstrap.ReflectionHelper;
 import net.dv8tion.jda.api.JDA;
+import net.dv8tion.jda.api.interactions.InteractionContextType;
 import net.dv8tion.jda.api.interactions.commands.build.CommandData;
 import net.dv8tion.jda.api.interactions.commands.build.SlashCommandData;
 import net.dv8tion.jda.api.requests.restaction.CommandListUpdateAction;
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
-import org.reflections.Reflections;
 
-import java.lang.reflect.Modifier;
+import java.util.ArrayList;
-import java.util.*;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.function.Consumer;
 
-public class CommandManager {
+/**
+ * Instance-based {@link CommandRegistry} owning the discovered command map.
+ */
+public class CommandManager implements CommandRegistry {
 
     private static final Logger logger = LogManager.getLogger(CommandManager.class);
-    public static final Map<String, CommandContainer> commands = new ConcurrentHashMap<>();
 
-    public static void init() {
+    private final Map<String, CommandContainer> commands = new ConcurrentHashMap<>();
+    private final ApplicationContext context;
+
+    /**
+     * Creates a command manager that can inject context-registered dependencies into reflectively
+     * loaded commands.
+     *
+     * @param context the application context; must not be {@code null}
+     */
+    public CommandManager(ApplicationContext context) {
+        Objects.requireNonNull(context, "ApplicationContext must not be null");
+        this.context = context;
+    }
+
+    @Override
+    public int priority() {
+        return 30;
+    }
+
+    @Override
+    public void start() {
+        init();
+    }
+
+    public void init() {
         logger.info("Loading commands..");
 
         initCommands();
@@ -30,48 +62,56 @@ public class CommandManager {
         logger.info("Loaded {} commands!", commands.size());
     }
 
-    public static Command getCommand(String commandString) {
+    @Override
-        return getCommandContainer(commandString).getCommand();
+    public CommandContainer getCommandContainer(String name) {
+        return commands.getOrDefault(name, CommandContainer.NULL_COMMAND);
     }
 
-    public static CommandContainer getCommandContainer(String commandString) {
+    @Override
-        return commands.getOrDefault(commandString, CommandContainer.NULL_COMMAND);
+    public boolean hasCommand(String name) {
+        return commands.containsKey(name);
     }
 
-    public static void initCommands() {
+    /**
-        Set<Class<? extends Command>> classes = new Reflections("me.bobert.netneutrality.command").getSubTypesOf(Command.class);
+     * Exposes the live command map for call sites (and tests) that still iterate or mutate it
-        for (Class<? extends Command> s : classes) {
+     * directly. Prefer {@link #hasCommand(String)} / {@link #getCommandContainer(String)} where
-            try {
+     * possible.
-                if (Modifier.isAbstract(s.getModifiers())) {
+     *
-                    continue;
+     * @return the registered commands keyed by name
-                }
+     */
+    @Override
+    public Map<String, CommandContainer> getCommands() {
+        return commands;
+    }
 
-                Command command = s.getConstructor().newInstance();
+    public void initCommands() {
-                if (!command.isEnabled()) {
+        Consumer<Command> onLoaded = command -> {
-                    continue;
+            if (!command.isEnabled()) {
-                }
+                logger.info("Skipping command {} as it is disabled", command.getClass().getName());
-
+                return;
-                if (command.getCommandName() == null) {
-                    throw new IllegalArgumentException("Command name is null");
-                }
-
-                if (command.getDescription() == null && command.getType() == Command.Type.SLASH) {
-                    throw new IllegalArgumentException("Command description is null");
-                }
-
-                CommandContainer container = new CommandContainer(command);
-                container.init();
-
-                if (!commands.containsKey(command.getCommandName())) {
-                    commands.put(command.getCommandName(), container);
-                }
-            } catch (Exception e) {
-                logger.error("Failed to load command {}: {}", s.getSimpleName(), e.getMessage());
             }
-        }
+
+            if (command.getCommandName() == null) {
+                logger.error("Failed to load command {}: Command name is null", command.getClass().getName());
+                return;
+            }
+
+            if (command.getDescription() == null && command.getType() == Command.Type.SLASH) {
+                logger.error("Failed to load command {}: Command description is null", command.getClass().getName());
+                return;
+            }
+
+            CommandContainer container = new CommandContainer(command);
+            if (!commands.containsKey(command.getCommandName())) {
+                commands.put(command.getCommandName(), container);
+            }
+        };
+
+        ReflectionHelper.loadCommands(Command.class, context, onLoaded);
     }
 
-    public static void registerSlashCommands(JDA jda) {
+    @Override
+    public void registerSlashCommands(JDA jda) {
         CommandListUpdateAction commandListUpdateAction = jda.updateCommands();
         List<CommandData> slashCommands = new ArrayList<>();
 
@@ -83,9 +123,9 @@ public class CommandManager {
             logger.debug("Registering slash command: {}", command.getCommandName());
 
             try {
-                SlashCommandData data = container.getCommandOptions().getSlashCommandData();
+                SlashCommandData data = container.getSlashCommandData();
                 data.setDefaultPermissions(command.getSlashCommandPermission());
-                data.setGuildOnly(command.isGuildOnly());
+                data.setContexts(command.isGuildOnly() ? Set.of(InteractionContextType.GUILD) : Set.of(InteractionContextType.GUILD, InteractionContextType.BOT_DM));
 
                 slashCommands.add(data);
             } catch (Exception e) {

src/main/java/me/bobert/netneutrality/core/command/CommandOptionsBuilder.java

@@ -1,30 +1,35 @@
-package me.bobert.netneutrality.core.command.options;
+package me.bobert.netneutrality.core.command;
 /*
  * Copyright (c) anthorob
  *
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.command.Command;
 import net.dv8tion.jda.api.interactions.DiscordLocale;
+import net.dv8tion.jda.api.interactions.IntegrationType;
+import net.dv8tion.jda.api.interactions.InteractionContextType;
 import net.dv8tion.jda.api.interactions.commands.DefaultMemberPermissions;
-import net.dv8tion.jda.api.interactions.commands.build.*;
+import net.dv8tion.jda.api.interactions.commands.build.Commands;
+import net.dv8tion.jda.api.interactions.commands.build.OptionData;
+import net.dv8tion.jda.api.interactions.commands.build.SlashCommandData;
+import net.dv8tion.jda.api.interactions.commands.build.SubcommandData;
+import net.dv8tion.jda.api.interactions.commands.build.SubcommandGroupData;
 import net.dv8tion.jda.api.interactions.commands.localization.LocalizationFunction;
 import net.dv8tion.jda.api.interactions.commands.localization.LocalizationMap;
 import net.dv8tion.jda.api.utils.data.DataObject;
 import net.dv8tion.jda.internal.interactions.CommandDataImpl;
 
 import javax.annotation.Nonnull;
+import java.util.Collection;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.function.Predicate;
 
 public class CommandOptionsBuilder implements SlashCommandData {
-    private final Command command;
     private CommandDataImpl commandData;
 
     public CommandOptionsBuilder(Command.Type type, Command command) {
-        this.command = command;
 
         if (type == Command.Type.SLASH) {
             commandData = (CommandDataImpl) Commands.slash(command.getCommandName(), command.getDescription());
@@ -39,8 +44,8 @@ public class CommandOptionsBuilder implements SlashCommandData {
         }
     }
 
-    public CommandOptions build() {
+    public CommandDataImpl build() {
-        return new CommandOptions(command, commandData);
+        return commandData;
     }
 
     @Override
@@ -69,8 +74,13 @@ public class CommandOptionsBuilder implements SlashCommandData {
     }
 
     @Override
-    public @Nonnull SlashCommandData setGuildOnly(boolean guildOnly) {
+    public @Nonnull SlashCommandData setContexts(@Nonnull Collection<InteractionContextType> contexts) {
-        return commandData.setGuildOnly(guildOnly);
+        return commandData.setContexts(contexts);
+    }
+
+    @Override
+    public @Nonnull SlashCommandData setIntegrationTypes(@Nonnull Collection<IntegrationType> integrationTypes) {
+        return commandData.setIntegrationTypes(integrationTypes);
     }
 
     @Override
@@ -99,8 +109,13 @@ public class CommandOptionsBuilder implements SlashCommandData {
     }
 
     @Override
-    public boolean isGuildOnly() {
+    public @Nonnull Set<InteractionContextType> getContexts() {
-        return commandData.isGuildOnly();
+        return commandData.getContexts();
+    }
+
+    @Override
+    public @Nonnull Set<IntegrationType> getIntegrationTypes() {
+        return commandData.getIntegrationTypes();
     }
 
     @Override

src/main/java/me/bobert/netneutrality/core/command/CommandProcessor.java

@@ -6,74 +6,82 @@ package me.bobert.netneutrality.core.command;
  */
 
 import io.sentry.Sentry;
-import me.bobert.netneutrality.context.command.SlashCommandContext;
 import me.bobert.netneutrality.core.LogHandler;
-import me.bobert.netneutrality.core.command.options.CommandOptions;
+import me.bobert.netneutrality.core.command.precondition.CommandPrecondition;
+import me.bobert.netneutrality.core.command.precondition.GuildOnlyPrecondition;
+import me.bobert.netneutrality.core.command.precondition.PermissionPrecondition;
+import me.bobert.netneutrality.core.command.precondition.SlashCommandOnlyPrecondition;
 import me.bobert.netneutrality.core.context.CommandContext;
-import me.bobert.netneutrality.core.context.InteractionContext;
-import me.bobert.netneutrality.core.tasks.Task;
-import me.bobert.netneutrality.core.tasks.TaskManager;
 import me.bobert.netneutrality.exceptions.CommandExecutionException;
 import me.bobert.netneutrality.exceptions.GracefulContextError;
-import me.bobert.netneutrality.utils.UserFunction;
+import me.bobert.netneutrality.core.tasks.TaskManager;
-import net.dv8tion.jda.api.interactions.commands.OptionType;
+import me.bobert.netneutrality.shared.util.UserFunction;
 import net.dv8tion.jda.api.interactions.commands.build.OptionData;
-import net.dv8tion.jda.api.interactions.commands.build.SubcommandData;
-import net.dv8tion.jda.api.interactions.commands.build.SubcommandGroupData;
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 
-import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
-
+import java.util.Objects;
-import static java.util.function.Predicate.not;
-import static me.bobert.netneutrality.core.command.CommandExecutionResult.Result.*;
 
 public class CommandProcessor {
 
     private static final Logger logger = LogManager.getLogger(CommandProcessor.class);
     private final CommandContext context;
+    private final CommandRegistry commands;
+    private final TaskManager taskManager;
+    private final List<CommandPrecondition> preconditions;
+    private final UsageValidator usageValidator;
+    private final CommandResultHandler resultHandler;
 
-    public CommandProcessor(CommandContext context) {
+    public CommandProcessor(CommandContext context, CommandRegistry commands, TaskManager taskManager) {
+        this(context, commands, taskManager, defaultPreconditions(), new UsageValidator(), new CommandResultHandler());
+    }
+
+    public CommandProcessor(CommandContext context, CommandRegistry commands, TaskManager taskManager,
+                            List<CommandPrecondition> preconditions, UsageValidator usageValidator,
+                            CommandResultHandler resultHandler) {
         this.context = context;
+        this.commands = Objects.requireNonNull(commands, "commands");
+        this.taskManager = Objects.requireNonNull(taskManager, "taskManager");
+        this.preconditions = Objects.requireNonNull(preconditions, "preconditions");
+        this.usageValidator = Objects.requireNonNull(usageValidator, "usageValidator");
+        this.resultHandler = Objects.requireNonNull(resultHandler, "resultHandler");
+    }
+
+    private static List<CommandPrecondition> defaultPreconditions() {
+        return List.of(
+            new GuildOnlyPrecondition(),
+            new SlashCommandOnlyPrecondition(),
+            new PermissionPrecondition()
+        );
     }
 
     public void dispatch() {
-        if (!CommandManager.commands.containsKey(context.parseCommandName())) {
+        if (!commands.hasCommand(context.parseCommandName())) {
             return;
         }
 
-        CommandContainer container = CommandManager.getCommandContainer(context.parseCommandName());
+        CommandContainer container = commands.getCommandContainer(context.parseCommandName());
         Command command = container.getCommand();
         if (command == null) {
             throw new IllegalArgumentException("Context has no command");
         }
 
         context.setCommand(command);
-        if (command.isGuildOnly() && !context.isFromGuild()) {
-            context.replyEphemeral("This command is only available in a guild");
-            context.deleteMessage();
-            return;
-        }
 
-        if (command.isSlashCommandOnly() && !(context instanceof InteractionContext)) {
+        for (CommandPrecondition precondition : preconditions) {
-            context.replyEphemeral("This command is only available as a slash command");
+            if (!precondition.check(context, command)) {
-            return;
+                return;
+            }
         }
 
         try {
-            logger.info("Context ID: {}", context.getId());
+            logger.debug("Context ID: {}", context.getId());
             logger.info("Executing command {} on guild {}", command.getCommandName(), context.getGuild() == null ? "PrivateMessage" : context.getGuild().getId());
             configureSentry(command);
 
-            if (command.getType() == Command.Type.SLASH && !canExecute(command)) {
+            if (command.getType() == Command.Type.SLASH && !usageValidator.validate(context, container)) {
-                context.reply("You are not powerful enough, scrub");
-                return;
-            }
-
-            if (command.getType() == Command.Type.SLASH && !checkUsage(container.getCommandOptions())) {
                 return;
             }
 
@@ -88,31 +96,7 @@ public class CommandProcessor {
             }
 
             CommandExecutionResult commandExecutionResult = command.execute(context);
-            if (commandExecutionResult == null) {
+            resultHandler.handle(context, commandExecutionResult, taskManager);
-                throw new RuntimeException("CommandExecutionResult is null");
-            }
-
-            CommandExecutionResult.Result result = commandExecutionResult.getResult();
-            if (result == NOACTION) {
-                return;
-            }
-
-            if (result == TASK) {
-                TaskManager.getInstance().insert(context, commandExecutionResult.getTask());
-            }
-
-            String message = commandExecutionResult.getMessage();
-            if (result == ERROR) {
-                logger.error("Context[{}]: Error from command: {}", context.getId(), message, commandExecutionResult.getException());
-            }
-
-            if (result == WARN) {
-                logger.warn("Context[{}]: Warning from command: {}", context.getId(), message);
-            }
-
-            if (message != null) {
-                context.reply(message);
-            }
         } catch (GracefulContextError exception) {
             logger.error(exception.getMessage());
             context.replyEphemeral(exception.getMessage());
@@ -123,127 +107,6 @@ public class CommandProcessor {
         }
     }
 
-    private boolean checkUsage(CommandOptions commandOptions) {
-        List<SubcommandGroupData> groups = commandOptions.getSubcommandGroups();
-        List<SubcommandData> subcommands = commandOptions.getSubcommands();
-        List<OptionData> options = commandOptions.getOptions();
-        String[] possibleCommands = Arrays.stream(context.getFullCommand().split(" ")).skip(1).toArray(String[]::new);
-        if (possibleCommands.length == 0) {
-            if (!groups.isEmpty()) {
-                // missing subcommand group
-                context.reply(invalidUsage("missing subcommand group"));
-                return false;
-            }
-
-            if (!subcommands.isEmpty()) {
-                // missing subcommand
-                context.reply(invalidUsage("missing subcommand"));
-                return false;
-            }
-
-            return checkOptions(possibleCommands, 0, options);
-        }
-
-        SubcommandGroupData group = groups.stream().filter(data -> data.getName().equals(possibleCommands[0])).findFirst().orElse(null);
-        if (group == null) {
-            SubcommandData subcommand = subcommands.stream().filter(data -> data.getName().equals(possibleCommands[0])).findFirst().orElse(null);
-            if (subcommand == null) {
-                if (!groups.isEmpty()) {
-                    // no group found but one is expected
-                    context.reply(invalidUsage("unknown subcommand group"));
-                    return false;
-                }
-
-                if (!subcommands.isEmpty()) {
-                    // no subcommand found but one is expected
-                    context.reply(invalidUsage("unknown subcommand"));
-                    return false;
-                }
-
-                // no group found, no subcommand found, command with options only
-                return checkOptions(possibleCommands, 0, options);
-            }
-
-            // no group found, subcommand found
-            context.setSubcommand(subcommand);
-            return checkOptions(possibleCommands, 1, subcommand.getOptions());
-        }
-
-        if (possibleCommands.length < 2) {
-            // missing subcommand for group
-            context.reply(invalidUsage("missing subcommand for command group"));
-            return false;
-        }
-
-        SubcommandData subcommand = group.getSubcommands().stream().filter(data -> data.getName().equals(possibleCommands[1])).findFirst().orElse(null);
-        if (subcommand == null) {
-            // group found, no subcommand found
-            context.reply(invalidUsage("unknown subcommand in command group"));
-            return false;
-        }
-
-        // group found, subcommand found
-        context.setSubcommandGroup(group);
-        context.setSubcommand(subcommand);
-        return checkOptions(possibleCommands, 2, subcommand.getOptions());
-    }
-
-    private boolean checkOptions(String[] args, int skip, List<OptionData> options) {
-        if (context instanceof InteractionContext) {
-            context.setCurrentCommandOptions(args, options);
-            return true; // slash commands are validated by discord
-        }
-
-        List<String> arguments = new ArrayList<>(Arrays.stream(args).skip(skip).toList());
-        int required = options.stream().filter(OptionData::isRequired).toList().size();
-        int optional = options.stream().filter(not(OptionData::isRequired)).toList().size();
-
-        if (arguments.size() < required) {
-            context.reply(invalidUsage("missing one or more required arguments"));
-            return false;
-        }
-
-        // check if last option is a string, if it is then combine all remaining strings into one
-        // ["@user", "you", "are", "banned"] becomes ["@user", "you are banned"]
-        if (!options.isEmpty() && arguments.size() > 1) {
-            OptionData last = options.get(options.size() - 1);
-            if (last.getType() == OptionType.STRING) {
-                List<String> lastArgs = arguments.stream().skip(options.size() - 1).toList();
-                arguments.removeAll(lastArgs);
-                arguments.add(String.join(" ", lastArgs));
-            }
-        }
-
-        if (arguments.size() > required + optional) {
-            context.reply(invalidUsage("too many arguments"));
-            return false;
-        }
-
-        context.setCurrentCommandOptions(arguments.toArray(String[]::new), options);
-        return true;
-    }
-
-    private boolean canExecute(Command command) {
-        if (command.canBeExecutedFrom(context.getChannel())) {
-            return true;
-        }
-
-        if (context instanceof SlashCommandContext) {
-            return true; // no further checks since slash perms are handled by guild settings on discord
-        }
-
-        if (command.canBeExecutedBy(context.getGuildUser())) {
-            return true;
-        }
-
-        return command.needAdmin() && UserFunction.isAdmin(context.getGuildUser());
-    }
-
-    private String invalidUsage(String message) {
-        return String.format("Invalid usage for command: %s\n" +
-                "Use **/help %s** for information on how to use this command", message, context.getCommand().getCommandName());
-    }
-
     private void configureSentry(Command command) {
         Sentry.configureScope(scope -> {
             scope.setTag("command", command.getCommandName());

src/main/java/me/bobert/netneutrality/core/command/CommandRegistry.java

@@ -0,0 +1,51 @@
+package me.bobert.netneutrality.core.command;
+
+/*
+ * Copyright (c) anthorob
+ *
+ * https://discord.gg/qUa6zNFZsd
+ */
+
+import me.bobert.netneutrality.bootstrap.Lifecycle;
+import net.dv8tion.jda.api.JDA;
+
+import java.util.Map;
+
+/**
+ * Owns the bot command registry and slash-command registration against Discord.
+ *
+ * <p>As a {@link Lifecycle} component it discovers and loads commands on {@link #start()}.
+ */
+public interface CommandRegistry extends Lifecycle {
+
+    /**
+     * Returns the container for the named command, or a null-object container if unknown.
+     *
+     * @param name the command name
+     * @return the command container
+     */
+    CommandContainer getCommandContainer(String name);
+
+    /**
+     * Whether a command with the given name is registered.
+     *
+     * @param name the command name
+     * @return {@code true} if registered
+     */
+    boolean hasCommand(String name);
+
+    /**
+     * Pushes every enabled slash command up to Discord via the given JDA instance.
+     *
+     * @param jda the connected JDA client
+     */
+    void registerSlashCommands(JDA jda);
+
+    /**
+     * Returns the live command map keyed by command name.
+     *
+     * @return the registered commands
+     */
+    Map<String, CommandContainer> getCommands();
+}
+

src/main/java/me/bobert/netneutrality/core/command/CommandResultHandler.java

@@ -0,0 +1,49 @@
+package me.bobert.netneutrality.core.command;
+/*
+ * Copyright (c) anthorob
+ *
+ * https://discord.gg/qUa6zNFZsd
+ */
+
+import me.bobert.netneutrality.core.context.CommandContext;
+import me.bobert.netneutrality.core.tasks.TaskManager;
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+import static me.bobert.netneutrality.core.command.CommandExecutionResult.Result.ERROR;
+import static me.bobert.netneutrality.core.command.CommandExecutionResult.Result.NOACTION;
+import static me.bobert.netneutrality.core.command.CommandExecutionResult.Result.TASK;
+import static me.bobert.netneutrality.core.command.CommandExecutionResult.Result.WARN;
+
+public class CommandResultHandler {
+
+    private static final Logger logger = LogManager.getLogger(CommandResultHandler.class);
+
+    public void handle(CommandContext context, CommandExecutionResult commandExecutionResult, TaskManager taskManager) {
+        if (commandExecutionResult == null) {
+            throw new RuntimeException("CommandExecutionResult is null");
+        }
+
+        CommandExecutionResult.Result result = commandExecutionResult.getResult();
+        if (result == NOACTION) {
+            return;
+        }
+
+        if (result == TASK) {
+            taskManager.insert(context, commandExecutionResult.getTask());
+        }
+
+        String message = commandExecutionResult.getMessage();
+        if (result == ERROR) {
+            logger.error("Context[{}]: Error from command: {}", context.getId(), message, commandExecutionResult.getException());
+        }
+
+        if (result == WARN) {
+            logger.warn("Context[{}]: Warning from command: {}", context.getId(), message);
+        }
+
+        if (message != null) {
+            context.reply(message);
+        }
+    }
+}

src/main/java/me/bobert/netneutrality/core/command/UsageValidator.java

@@ -0,0 +1,97 @@
+package me.bobert.netneutrality.core.command;
+/*
+ * Copyright (c) anthorob
+ *
+ * https://discord.gg/qUa6zNFZsd
+ */
+
+import me.bobert.netneutrality.core.context.CommandContext;
+import net.dv8tion.jda.api.interactions.commands.build.OptionData;
+import net.dv8tion.jda.api.interactions.commands.build.SubcommandData;
+import net.dv8tion.jda.api.interactions.commands.build.SubcommandGroupData;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+public class UsageValidator {
+
+    public boolean validate(CommandContext context, CommandContainer container) {
+        List<SubcommandGroupData> groups = container.getSubcommandGroups();
+        List<SubcommandData> subcommands = container.getSubcommands();
+        List<OptionData> options = container.getOptions();
+        String[] possibleCommands = Arrays.stream(context.getFullCommand().split(" ")).skip(1).toArray(String[]::new);
+        if (possibleCommands.length == 0) {
+            if (!groups.isEmpty()) {
+                context.reply(invalidUsage("missing subcommand group", context));
+                return false;
+            }
+
+            if (!subcommands.isEmpty()) {
+                context.reply(invalidUsage("missing subcommand", context));
+                return false;
+            }
+
+            return checkOptions(context, possibleCommands, 0, options);
+        }
+
+        SubcommandGroupData group = groups.stream().filter(data -> data.getName().equals(possibleCommands[0])).findFirst().orElse(null);
+        if (group == null) {
+            SubcommandData subcommand = subcommands.stream().filter(data -> data.getName().equals(possibleCommands[0])).findFirst().orElse(null);
+            if (subcommand == null) {
+                if (!groups.isEmpty()) {
+                    context.reply(invalidUsage("unknown subcommand group", context));
+                    return false;
+                }
+
+                if (!subcommands.isEmpty()) {
+                    context.reply(invalidUsage("unknown subcommand", context));
+                    return false;
+                }
+
+                return checkOptions(context, possibleCommands, 0, options);
+            }
+
+            context.setSubcommand(subcommand);
+            return checkOptions(context, possibleCommands, 1, subcommand.getOptions());
+        }
+
+        if (possibleCommands.length < 2) {
+            context.reply(invalidUsage("missing subcommand for command group", context));
+            return false;
+        }
+
+        SubcommandData subcommand = group.getSubcommands().stream().filter(data -> data.getName().equals(possibleCommands[1])).findFirst().orElse(null);
+        if (subcommand == null) {
+            context.reply(invalidUsage("unknown subcommand in command group", context));
+            return false;
+        }
+
+        context.setSubcommandGroup(group);
+        context.setSubcommand(subcommand);
+        return checkOptions(context, possibleCommands, 2, subcommand.getOptions());
+    }
+
+    private boolean checkOptions(CommandContext context, String[] args, int skip, List<OptionData> options) {
+        if (context.isInteraction()) {
+            context.setCurrentCommandOptions(args, options);
+            return true;
+        }
+
+        List<String> arguments = new ArrayList<>(Arrays.stream(args).skip(skip).toList());
+        int required = options.stream().filter(OptionData::isRequired).toList().size();
+
+        if (arguments.size() < required) {
+            context.reply(invalidUsage("missing one or more required arguments", context));
+            return false;
+        }
+
+        context.setCurrentCommandOptions(arguments.toArray(String[]::new), options);
+        return true;
+    }
+
+    private String invalidUsage(String message, CommandContext context) {
+        return String.format("Invalid usage for command: %s\n" +
+            "Use **/help %s** for information on how to use this command", message, context.getCommand().getCommandName());
+    }
+}

src/main/java/me/bobert/netneutrality/core/command/impl/AbstractCommand.java

@@ -1,4 +1,4 @@
-package me.bobert.netneutrality.core.command;
+package me.bobert.netneutrality.core.command.impl;
 
 /*
  * Copyright (c) anthorob
@@ -6,6 +6,7 @@ package me.bobert.netneutrality.core.command;
  * https://discord.gg/qUa6zNFZsd
  */
 
+import me.bobert.netneutrality.core.command.Command;
 import net.dv8tion.jda.api.entities.Member;
 import net.dv8tion.jda.api.entities.channel.middleman.MessageChannel;
 import net.dv8tion.jda.api.interactions.commands.DefaultMemberPermissions;

src/main/java/me/bobert/netneutrality/core/command/impl/AdminCommand.java

@@ -1,11 +1,13 @@
-package me.bobert.netneutrality.core.command;
+package me.bobert.netneutrality.core.command.impl;
 /*
  * Copyright (c) anthorob
  *
  * https://discord.gg/qUa6zNFZsd
  */
 
-public abstract class AbstractAdminCommand extends AbstractCommand {
+import me.bobert.netneutrality.core.command.CommandCategory;
+
+public abstract class AdminCommand extends AbstractCommand {
 
     @Override
     public boolean needAdmin() {

src/main/java/me/bobert/netneutrality/core/command/impl/MessageMenuCommand.java

@@ -1,4 +1,4 @@
-package me.bobert.netneutrality.core.command;
+package me.bobert.netneutrality.core.command.impl;
 
 /*
  * Copyright (c) anthorob
@@ -7,11 +7,13 @@ package me.bobert.netneutrality.core.command;
  */
 
 import me.bobert.netneutrality.context.command.MessageMenuContext;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.CommandCategory;
+import me.bobert.netneutrality.core.command.CommandExecutionResult;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
 import me.bobert.netneutrality.core.context.CommandContext;
 import net.dv8tion.jda.api.entities.Message;
 
-public abstract class AbstractMessageMenuCommand extends AbstractCommand {
+public abstract class MessageMenuCommand extends AbstractCommand {
     @Override
     public String getDescription() {
         return null;

src/main/java/me/bobert/netneutrality/core/command/impl/MusicCommand.java

@@ -0,0 +1,117 @@
+package me.bobert.netneutrality.core.command.impl;
+/*
+ * Copyright (c) anthorob
+ *
+ * https://discord.gg/qUa6zNFZsd
+ */
+
+import me.bobert.netneutrality.core.command.CommandCategory;
+import me.bobert.netneutrality.db.service.GuildServiceProvider;
+import me.bobert.netneutrality.db.GSettings;
+import me.bobert.netneutrality.db.service.GuildService;
+import me.bobert.netneutrality.shared.util.UserFunction;
+import net.dv8tion.jda.api.entities.Guild;
+import net.dv8tion.jda.api.entities.Member;
+import net.dv8tion.jda.api.entities.Role;
+import net.dv8tion.jda.api.entities.channel.ChannelType;
+import net.dv8tion.jda.api.entities.channel.middleman.GuildMessageChannel;
+import net.dv8tion.jda.api.entities.channel.middleman.MessageChannel;
+
+import java.util.Objects;
+
+public abstract class MusicCommand extends AbstractCommand {
+
+    /**
+     * Injected guild-service provider when constructed via DI.
+     */
+    private final GuildServiceProvider guildServices;
+
+    /**
+     * Preferred constructor for DI.
+     *
+     * @param guildServices the shared guild service provider, must not be {@code null}
+     */
+    public MusicCommand(GuildServiceProvider guildServices) {
+        Objects.requireNonNull(guildServices, "GuildServiceProvider must not be null");
+        this.guildServices = guildServices;
+    }
+
+    /**
+     * Resolves the {@link GuildService} for a guild via the injected provider.
+     *
+     * @param guild the guild
+     * @return the guild service
+     */
+    protected final GuildService guildService(Guild guild) {
+        return guildServices.get(guild);
+    }
+
+    /**
+     * Resolves the {@link GuildService} for a guild id via the injected provider.
+     *
+     * @param guildId the guild id
+     * @return the guild service
+     */
+    protected final GuildService guildService(String guildId) {
+        return guildServices.get(guildId);
+    }
+
+    @Override
+    public boolean needAdmin() {
+        return false;
+    }
+
+    @Override
+    public boolean isGuildOnly() {
+        return true;
+    }
+
+    @Override
+    public CommandCategory getCategory() {
+        return CommandCategory.MUSIC;
+    }
+
+    @Override
+    public boolean canBeExecutedBy(Member member) {
+        if (member == null) {
+            return true;
+        }
+
+        Guild guild = member.getGuild();
+
+        String roleDb = guildService(guild.getId()).getGuildSettingService().getSetting(GSettings.MUSIC_ROLE);
+
+        if (roleDb != null && !roleDb.isEmpty()) {
+            if (UserFunction.isAdmin(member)) {
+                return true;
+            }
+
+            Role neededRole = guild.getRoleById(roleDb);
+            if (neededRole == null) {
+                // Role doesn't exist on guild anymore, remove from db
+                guildService(guild.getId()).getGuildSettingService().setSettingValue(GSettings.MUSIC_ROLE, null);
+                return true;
+            }
+
+            return member.getRoles().contains(neededRole);
+        }
+
+        return true;
+    }
+
+    @Override
+    public boolean canBeExecutedFrom(MessageChannel channel) {
+        if (channel instanceof GuildMessageChannel guildMessageChannel) {
+            if (channel.getType() != ChannelType.TEXT) {
+                return false;
+            }
+
+            String channelDb = guildService(guildMessageChannel.getGuild()).getGuildSettingService().getSetting(GSettings.MUSIC_CHANNEL);
+            if (channelDb != null && !channelDb.isEmpty()) {
+                return channelDb.equals(channel.getId());
+            }
+        }
+
+        return true;
+    }
+}

src/main/java/me/bobert/netneutrality/core/command/impl/UserMenuCommand.java

@@ -1,4 +1,4 @@
-package me.bobert.netneutrality.core.command;
+package me.bobert.netneutrality.core.command.impl;
 
 /*
  * Copyright (c) anthorob
@@ -7,11 +7,12 @@ package me.bobert.netneutrality.core.command;
  */
 
 import me.bobert.netneutrality.context.command.UserMenuContext;
-import me.bobert.netneutrality.core.command.options.CommandOptionsBuilder;
+import me.bobert.netneutrality.core.command.CommandExecutionResult;
+import me.bobert.netneutrality.core.command.CommandOptionsBuilder;
 import me.bobert.netneutrality.core.context.CommandContext;
 import net.dv8tion.jda.api.entities.User;
 
-public abstract class AbstractUserMenuCommand extends AbstractCommand {
+public abstract class UserMenuCommand extends AbstractCommand {
     @Override
     public String getDescription() {
         return null;

src/main/java/me/bobert/netneutrality/core/command/options/CommandOption.java

@@ -5,7 +5,11 @@ package me.bobert.netneutrality.core.command.options;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import net.dv8tion.jda.api.entities.*;
+import net.dv8tion.jda.api.entities.IMentionable;
+import net.dv8tion.jda.api.entities.Member;
+import net.dv8tion.jda.api.entities.Message;
+import net.dv8tion.jda.api.entities.Role;
+import net.dv8tion.jda.api.entities.User;
 import net.dv8tion.jda.api.entities.channel.ChannelType;
 import net.dv8tion.jda.api.entities.channel.unions.GuildChannelUnion;
 import net.dv8tion.jda.api.interactions.commands.OptionType;
@@ -29,10 +33,8 @@ public interface CommandOption {
      * <br>This is represented as an {@link Message.Attachment#isEphemeral() ephemeral} attachment which will only be hosted for up to 2 weeks.
      * If you want a permanent reference, you must download it.
      *
-     * @throws IllegalStateException
-     *         If this option {@link #getType() type} is not {@link OptionType#ATTACHMENT}
-     *
      * @return {@link net.dv8tion.jda.api.entities.Message.Attachment Attachment}
+     * @throws IllegalStateException If this option {@link #getType() type} is not {@link OptionType#ATTACHMENT}
      */
     Message.Attachment getAsAttachment();
 
@@ -48,10 +50,8 @@ public interface CommandOption {
     /**
      * The boolean value.
      *
-     * @throws IllegalStateException
-     *         If this option is not of type {@link OptionType#BOOLEAN BOOLEAN}
-     *
      * @return The boolean value
+     * @throws IllegalStateException If this option is not of type {@link OptionType#BOOLEAN BOOLEAN}
      */
     boolean getAsBoolean();
 
@@ -59,12 +59,9 @@ public interface CommandOption {
      * The long value for this option.
      * <br>This will be the ID of any resolved entity such as {@link Role} or {@link Member}.
      *
-     * @throws IllegalStateException
-     *         If this option {@link #getType() type} cannot be converted to a long
-     * @throws NumberFormatException
-     *         If this option is of type {@link OptionType#STRING STRING} and could not be parsed to a valid long value
-     *
      * @return The long value
+     * @throws IllegalStateException If this option {@link #getType() type} cannot be converted to a long
+     * @throws NumberFormatException If this option is of type {@link OptionType#STRING STRING} and could not be parsed to a valid long value
      */
     long getAsLong();
 
@@ -74,36 +71,27 @@ public interface CommandOption {
      *
      * <p><b>It is highly recommended to assert int values by using {@link OptionData#setRequiredRange(long, long)}</b>
      *
-     * @throws IllegalStateException
-     *         If this option {@link #getType() type} cannot be converted to a long
-     * @throws NumberFormatException
-     *         If this option is of type {@link OptionType#STRING STRING} and could not be parsed to a valid long value
-     * @throws ArithmeticException
-     *         If the provided integer value cannot fit into a 32bit signed int
-     *
      * @return The int value
+     * @throws IllegalStateException If this option {@link #getType() type} cannot be converted to a long
+     * @throws NumberFormatException If this option is of type {@link OptionType#STRING STRING} and could not be parsed to a valid long value
+     * @throws ArithmeticException   If the provided integer value cannot fit into a 32bit signed int
      */
     int getAsInt();
 
     /**
      * The double value for this option.
      *
-     * @throws IllegalStateException
-     *         If this option {@link #getType() type} cannot be converted to a double
-     * @throws NumberFormatException
-     *         If this option is of type {@link OptionType#STRING STRING} and could not be parsed to a valid double value
-     *
      * @return The double value
+     * @throws IllegalStateException If this option {@link #getType() type} cannot be converted to a double
+     * @throws NumberFormatException If this option is of type {@link OptionType#STRING STRING} and could not be parsed to a valid double value
      */
     double getAsDouble();
 
     /**
      * The resolved {@link IMentionable} instance for this option value.
      *
-     * @throws IllegalStateException
-     *         If the mentioned entity is not resolvable
-     *
      * @return The resolved {@link IMentionable}
+     * @throws IllegalStateException If the mentioned entity is not resolvable
      */
     IMentionable getAsMentionable();
 
@@ -111,42 +99,34 @@ public interface CommandOption {
      * The resolved {@link Member} for this option value.
      * <br>Note that {@link OptionType#USER OptionType.USER} can also accept users that are not members of a guild, in which case this will be null!
      *
-     * @throws IllegalStateException
-     *         If this option is not of type {@link OptionType#USER USER} or {@link OptionType#MENTIONABLE MENTIONABLE}
-     *
      * @return The resolved {@link Member}, or null
+     * @throws IllegalStateException If this option is not of type {@link OptionType#USER USER} or {@link OptionType#MENTIONABLE MENTIONABLE}
      */
     Member getAsMember();
 
     /**
      * The resolved {@link User} for this option value.
      *
-     * @throws IllegalStateException
-     *         If this option is not of type {@link OptionType#USER USER} or
-     *         {@link OptionType#MENTIONABLE MENTIONABLE} without a resolved user
-     *
      * @return The resolved {@link User}
+     * @throws IllegalStateException If this option is not of type {@link OptionType#USER USER} or
+     *                               {@link OptionType#MENTIONABLE MENTIONABLE} without a resolved user
      */
     User getAsUser();
 
     /**
      * The resolved {@link Role} for this option value.
      *
-     * @throws IllegalStateException
-     *         If this option is not of type {@link OptionType#ROLE ROLE} or
-     *         {@link OptionType#MENTIONABLE MENTIONABLE} without a resolved role
-     *
      * @return The resolved {@link Role}
+     * @throws IllegalStateException If this option is not of type {@link OptionType#ROLE ROLE} or
+     *                               {@link OptionType#MENTIONABLE MENTIONABLE} without a resolved role
      */
     Role getAsRole();
 
     /**
      * The {@link ChannelType} for the resolved channel.
      *
-     * @throws IllegalStateException
-     *         If this option is not of type {@link OptionType#CHANNEL CHANNEL}
-     *
      * @return The {@link ChannelType}
+     * @throws IllegalStateException If this option is not of type {@link OptionType#CHANNEL CHANNEL}
      */
     ChannelType getChannelType();
 
@@ -154,11 +134,9 @@ public interface CommandOption {
      * The resolved {@link net.dv8tion.jda.api.entities.channel.middleman.GuildChannel} for this option value.
      * <br>Note that {@link OptionType#CHANNEL OptionType.CHANNEL} can accept channels of any type!
      *
-     * @throws IllegalStateException
-     *         If this option is not of type {@link OptionType#CHANNEL CHANNEL}
-     *         or could not be resolved for unexpected reasons
-     *
      * @return The resolved {@link net.dv8tion.jda.api.entities.channel.middleman.GuildChannel}
+     * @throws IllegalStateException If this option is not of type {@link OptionType#CHANNEL CHANNEL}
+     *                               or could not be resolved for unexpected reasons
      */
     GuildChannelUnion getAsChannel();
 }

src/main/java/me/bobert/netneutrality/core/command/options/CommandOptions.java

@@ -1,170 +0,0 @@
-package me.bobert.netneutrality.core.command.options;
-/*
- * Copyright (c) anthorob
- *
- * https://discord.gg/qUa6zNFZsd
- */
-
-import me.bobert.netneutrality.core.command.Command;
-import net.dv8tion.jda.api.entities.channel.ChannelType;
-import net.dv8tion.jda.api.interactions.commands.build.OptionData;
-import net.dv8tion.jda.api.interactions.commands.build.SlashCommandData;
-import net.dv8tion.jda.api.interactions.commands.build.SubcommandData;
-import net.dv8tion.jda.api.interactions.commands.build.SubcommandGroupData;
-import net.dv8tion.jda.internal.interactions.CommandDataImpl;
-
-import java.util.List;
-import java.util.Set;
-import java.util.StringJoiner;
-
-public class CommandOptions {
-    private final Command command;
-    private final CommandDataImpl commandData;
-    private final List<OptionData> options;
-    private final List<SubcommandData> subcommands;
-    private final List<SubcommandGroupData> subcommandGroups;
-
-    public CommandOptions(Command command, CommandDataImpl commandData) {
-        this.command = command;
-        this.commandData = commandData;
-        this.options = commandData.getOptions();
-        this.subcommands = commandData.getSubcommands();
-        this.subcommandGroups = commandData.getSubcommandGroups();
-    }
-
-    public Command getCommand() {
-        return command;
-    }
-
-    public SlashCommandData getSlashCommandData() {
-        return commandData;
-    }
-
-    public List<OptionData> getOptions() {
-        return options;
-    }
-
-    public List<SubcommandData> getSubcommands() {
-        return subcommands;
-    }
-
-    public List<SubcommandGroupData> getSubcommandGroups() {
-        return subcommandGroups;
-    }
-
-    public boolean isEmpty() {
-        return options.isEmpty() && subcommands.isEmpty() && subcommandGroups.isEmpty();
-    }
-
-    public String printUsage() {
-        StringBuilder usage = new StringBuilder();
-        if (!options.isEmpty()) {
-            usage.append("- Usage: /").append(command.getCommandName());
-            for (OptionData option : options) {
-                usage.append(" <").append(option.getName()).append(">");
-            }
-
-            usage.append(printOptions(options, null, false));
-        }
-
-        if (!subcommands.isEmpty()) {
-            for (SubcommandData subcommand : subcommands) {
-                usage.append("- Usage: /").append(command.getCommandName()).append(" ").append(subcommand.getName());
-
-                for (OptionData option : subcommand.getOptions()) {
-                    usage.append(" <").append(option.getName()).append(">");
-                }
-
-                usage.append(" (").append(subcommand.getDescription()).append(")");
-                usage.append(printOptions(subcommand.getOptions(), null, false));
-
-                usage.append("\n");
-            }
-        }
-
-        if (!subcommandGroups.isEmpty()) {
-            for (SubcommandGroupData subcommandGroup : subcommandGroups) {
-                usage.append("- Subcommand: /").append(command.getCommandName())
-                        .append(" ").append(subcommandGroup.getName())
-                        .append(" (").append(subcommandGroup.getDescription()).append(")")
-                        .append("\n");
-
-                for (SubcommandData subcommand : subcommandGroup.getSubcommands()) {
-                    usage.append("  - Usage: /").append(command.getCommandName())
-                            .append(" ").append(subcommandGroup.getName())
-                            .append(" ").append(subcommand.getName());
-
-                    for (OptionData option : subcommand.getOptions()) {
-                        usage.append(" <").append(option.getName()).append(">");
-                    }
-
-                    usage.append(printOptions(subcommand.getOptions(), subcommand.getDescription(), true));
-
-                    usage.append("\n");
-                }
-            }
-        }
-
-        if (!isEmpty()) {
-            usage.append("\n\n-# *: required argument");
-        }
-
-        return usage.toString();
-    }
-
-    private String printOptions(List<OptionData> options, String description, boolean group) {
-        StringBuilder usage = new StringBuilder();
-
-        if (description != null) {
-            usage.append(" (").append(description).append(")");
-        }
-
-        for (OptionData option : options) {
-            usage.append("\n");
-            if (group) usage.append("  ");
-            usage.append("  - ");
-            if (option.isRequired()) {
-                usage.append("*");
-            }
-            usage.append(option.getName()).append(": ").append(option.getDescription());
-
-            if (option.getMinValue() != null) {
-                usage.append(" [Min value: ").append(option.getMinValue().longValue()).append("]");
-            }
-
-            if (option.getMaxValue() != null) {
-                usage.append(" [Max value: ").append(option.getMaxValue().longValue()).append("]");
-            }
-
-            if (option.getMinLength() != null) {
-                usage.append(" [Min length: ").append(option.getMinLength().longValue()).append("]");
-            }
-
-            if (option.getMaxLength() != null) {
-                usage.append(" [Max length: ").append(option.getMaxLength().longValue()).append("]");
-            }
-
-            List<net.dv8tion.jda.api.interactions.commands.Command.Choice> choices = option.getChoices();
-            if (!choices.isEmpty()) {
-                StringJoiner joiner = new StringJoiner(", ");
-                for (net.dv8tion.jda.api.interactions.commands.Command.Choice choice : choices) {
-                    joiner.add(choice.getAsString());
-                }
-
-                usage.append(" [Available choices: ").append(joiner).append("]");
-            }
-
-            Set<ChannelType> requiredChannelTypes = option.getChannelTypes();
-            if (!requiredChannelTypes.isEmpty()) {
-                StringJoiner joiner = new StringJoiner(", ");
-                for (ChannelType type : requiredChannelTypes) {
-                    joiner.add(type.name());
-                }
-
-                usage.append(" [Required channel types: ").append(joiner).append("]");
-            }
-        }
-
-        return usage.toString();
-    }
-}

src/main/java/me/bobert/netneutrality/core/command/options/MessageCommandOption.java

@@ -5,7 +5,11 @@ package me.bobert.netneutrality.core.command.options;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import net.dv8tion.jda.api.entities.*;
+import net.dv8tion.jda.api.entities.IMentionable;
+import net.dv8tion.jda.api.entities.Member;
+import net.dv8tion.jda.api.entities.Message;
+import net.dv8tion.jda.api.entities.Role;
+import net.dv8tion.jda.api.entities.User;
 import net.dv8tion.jda.api.entities.channel.ChannelType;
 import net.dv8tion.jda.api.entities.channel.unions.GuildChannelUnion;
 import net.dv8tion.jda.api.interactions.commands.OptionType;
@@ -116,6 +120,10 @@ public class MessageCommandOption implements CommandOption {
 
     @Override
     public User getAsUser() {
+        if (value instanceof Member) {
+            return ((Member) value).getUser();
+        }
+
         if (value instanceof User) {
             return (User) value;
         }
@@ -149,9 +157,9 @@ public class MessageCommandOption implements CommandOption {
     @Override
     public String toString() {
         return "MessageCommandOption{" +
-                "name=" + data.getName() +
+            "name=" + data.getName() +
-                ", type=" + type +
+            ", type=" + type +
-                ", value=" + value +
+            ", value=" + value +
-                '}';
+            '}';
     }
 }

src/main/java/me/bobert/netneutrality/core/command/options/SlashCommandOption.java

@@ -5,7 +5,11 @@ package me.bobert.netneutrality.core.command.options;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import net.dv8tion.jda.api.entities.*;
+import net.dv8tion.jda.api.entities.IMentionable;
+import net.dv8tion.jda.api.entities.Member;
+import net.dv8tion.jda.api.entities.Message;
+import net.dv8tion.jda.api.entities.Role;
+import net.dv8tion.jda.api.entities.User;
 import net.dv8tion.jda.api.entities.channel.ChannelType;
 import net.dv8tion.jda.api.entities.channel.unions.GuildChannelUnion;
 import net.dv8tion.jda.api.interactions.commands.OptionMapping;

src/main/java/me/bobert/netneutrality/core/command/precondition/CommandPrecondition.java

@@ -0,0 +1,17 @@
+package me.bobert.netneutrality.core.command.precondition;
+/*
+ * Copyright (c) anthorob
+ *
+ * https://discord.gg/qUa6zNFZsd
+ */
+
+import me.bobert.netneutrality.core.command.Command;
+import me.bobert.netneutrality.core.context.CommandContext;
+
+public interface CommandPrecondition {
+    /**
+     * Returns true if the precondition passes and execution should continue,
+     * or false if it failed (the implementation is responsible for sending any reply).
+     */
+    boolean check(CommandContext context, Command command);
+}

src/main/java/me/bobert/netneutrality/core/command/precondition/GuildOnlyPrecondition.java

@@ -0,0 +1,23 @@
+package me.bobert.netneutrality.core.command.precondition;
+/*
+ * Copyright (c) anthorob
+ *
+ * https://discord.gg/qUa6zNFZsd
+ */
+
+import me.bobert.netneutrality.core.command.Command;
+import me.bobert.netneutrality.core.context.CommandContext;
+
+public class GuildOnlyPrecondition implements CommandPrecondition {
+
+    @Override
+    public boolean check(CommandContext context, Command command) {
+        if (command.isGuildOnly() && !context.isFromGuild()) {
+            context.replyEphemeral("This command is only available in a guild");
+            context.deleteMessage();
+            return false;
+        }
+
+        return true;
+    }
+}

src/main/java/me/bobert/netneutrality/core/command/precondition/PermissionPrecondition.java

@@ -0,0 +1,39 @@
+package me.bobert.netneutrality.core.command.precondition;
+/*
+ * Copyright (c) anthorob
+ *
+ * https://discord.gg/qUa6zNFZsd
+ */
+
+import me.bobert.netneutrality.core.command.Command;
+import me.bobert.netneutrality.core.context.CommandContext;
+import me.bobert.netneutrality.shared.util.UserFunction;
+
+public class PermissionPrecondition implements CommandPrecondition {
+
+    @Override
+    public boolean check(CommandContext context, Command command) {
+        if (command.getType() != Command.Type.SLASH) {
+            return true;
+        }
+
+        if (context.canSkipPermissionCheck()) {
+            return true;
+        }
+
+        if (command.canBeExecutedFrom(context.getChannel())) {
+            return true;
+        }
+
+        if (command.canBeExecutedBy(context.getGuildUser())) {
+            return true;
+        }
+
+        if (command.needAdmin() && UserFunction.isAdmin(context.getGuildUser())) {
+            return true;
+        }
+
+        context.reply("You are not powerful enough, scrub");
+        return false;
+    }
+}

src/main/java/me/bobert/netneutrality/core/command/precondition/SlashCommandOnlyPrecondition.java

@@ -0,0 +1,22 @@
+package me.bobert.netneutrality.core.command.precondition;
+/*
+ * Copyright (c) anthorob
+ *
+ * https://discord.gg/qUa6zNFZsd
+ */
+
+import me.bobert.netneutrality.core.command.Command;
+import me.bobert.netneutrality.core.context.CommandContext;
+
+public class SlashCommandOnlyPrecondition implements CommandPrecondition {
+
+    @Override
+    public boolean check(CommandContext context, Command command) {
+        if (command.isSlashCommandOnly() && !context.isInteraction()) {
+            context.replyEphemeral("This command is only available as a slash command");
+            return false;
+        }
+
+        return true;
+    }
+}

src/main/java/me/bobert/netneutrality/core/context/AbstractContext.java

@@ -6,7 +6,6 @@ package me.bobert.netneutrality.core.context;
  */
 
 import io.sentry.Sentry;
-import me.bobert.netneutrality.context.command.SlashCommandContext;
 import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.entities.Guild;
 import net.dv8tion.jda.api.entities.Member;

src/main/java/me/bobert/netneutrality/core/context/AsyncContext.java

@@ -1,17 +1,16 @@
-package me.bobert.netneutrality.context;
+package me.bobert.netneutrality.core.context;
 /*
  * Copyright (c) anthorob
  *
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.core.context.AbstractContext;
+import net.dv8tion.jda.api.components.MessageTopLevelComponent;
 import net.dv8tion.jda.api.entities.Message;
 import net.dv8tion.jda.api.entities.channel.ChannelType;
 import net.dv8tion.jda.api.events.Event;
 import net.dv8tion.jda.api.interactions.InteractionHook;
-import net.dv8tion.jda.api.interactions.components.LayoutComponent;
+import net.dv8tion.jda.api.modals.Modal;
-import net.dv8tion.jda.api.interactions.modals.Modal;
 import net.dv8tion.jda.api.utils.messages.MessageCreateData;
 import net.dv8tion.jda.api.utils.messages.MessageEditData;
 
@@ -97,7 +96,7 @@ public class AsyncContext extends AbstractContext {
     }
 
     @Override
-    public void reply(MessageCreateData messageCreateData, boolean ephemeral, List<LayoutComponent> components, Consumer<AsyncContext> consumer) {
+    public void reply(MessageCreateData messageCreateData, boolean ephemeral, List<MessageTopLevelComponent> components, Consumer<AsyncContext> consumer) {
         if (hook != null) {
             hook.sendMessage(messageCreateData).queue();
         }
@@ -118,7 +117,7 @@ public class AsyncContext extends AbstractContext {
     }
 
     @Override
-    public void edit(MessageEditData messageEditData, boolean ephemeral, List<LayoutComponent> components, Consumer<AsyncContext> consumer) {
+    public void edit(MessageEditData messageEditData, boolean ephemeral, List<MessageTopLevelComponent> components, Consumer<AsyncContext> consumer) {
         if (hook != null) {
             hook.editOriginal(messageEditData).queue();
         }

src/main/java/me/bobert/netneutrality/core/context/CommandContext.java

@@ -7,7 +7,7 @@ package me.bobert.netneutrality.core.context;
 
 import me.bobert.netneutrality.core.command.Command;
 import me.bobert.netneutrality.core.command.options.CommandOption;
-import me.bobert.netneutrality.utils.Settings;
+import me.bobert.netneutrality.utils.SettingsProvider;
 import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.entities.Guild;
 import net.dv8tion.jda.api.entities.Member;
@@ -17,7 +17,12 @@ import net.dv8tion.jda.api.interactions.commands.build.OptionData;
 import net.dv8tion.jda.api.interactions.commands.build.SubcommandData;
 import net.dv8tion.jda.api.interactions.commands.build.SubcommandGroupData;
 
-import java.util.*;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
 import java.util.function.Function;
 import java.util.function.Supplier;
 import java.util.stream.Collectors;
@@ -26,12 +31,14 @@ public abstract class CommandContext extends AbstractContext {
     private Command command;
     private SubcommandGroupData subcommandGroup;
     private SubcommandData subcommand;
-    private final Map <OptionData, String> invalidOptions = new HashMap<>();
+    private final Map<OptionData, String> invalidOptions = new HashMap<>();
     private final List<CommandOption> options;
+    private final SettingsProvider settings;
 
-    public CommandContext(JDA jda, Guild guild, MessageChannel channel, Member member, User user) {
+    public CommandContext(JDA jda, Guild guild, MessageChannel channel, Member member, User user, SettingsProvider settings) {
         super(jda, guild, channel, member, user);
         this.options = new ArrayList<>();
+        this.settings = settings;
     }
 
     public Command getCommand() {
@@ -70,16 +77,20 @@ public abstract class CommandContext extends AbstractContext {
     public <T> T getOption(String name, Supplier<? extends T> fallback, Function<? super CommandOption, ? extends T> resolver) {
         Objects.requireNonNull(resolver, "resolver cannot be null");
         CommandOption mapping = getOption(name);
-        if (mapping != null)
+        if (mapping != null) {
             return resolver.apply(mapping);
+        }
+
         return fallback == null ? null : fallback.get();
     }
 
     public <T> T getOption(String name, T fallback, Function<? super CommandOption, ? extends T> resolver) {
         Objects.requireNonNull(resolver, "resolver cannot be null");
         CommandOption mapping = getOption(name);
-        if (mapping != null)
+        if (mapping != null) {
             return resolver.apply(mapping);
+        }
+
         return fallback;
     }
 
@@ -89,7 +100,7 @@ public abstract class CommandContext extends AbstractContext {
 
     public CommandOption getOption(String name) {
         List<CommandOption> options = getOptionsByName(name);
-        return options.isEmpty() ? null : options.get(0);
+        return options.isEmpty() ? null : options.getFirst();
     }
 
     public List<CommandOption> getOptionsByName(String name) {
@@ -122,7 +133,7 @@ public abstract class CommandContext extends AbstractContext {
     }
 
     public boolean isMessageFromCreator() {
-        String creatorId = Settings.getInstance().get("NETNEUTRALITY_BOT_OWNER");
+        String creatorId = settings.get("NETNEUTRALITY_BOT_OWNER");
 
         return creatorId.equals(getDiscordUser().getId());
     }
@@ -133,6 +144,11 @@ public abstract class CommandContext extends AbstractContext {
 
     public abstract String getFullCommand();
 
+    public boolean isInteraction() {
+        return false;
+    }
 
-
+    public boolean canSkipPermissionCheck() {
+        return false;
+    }
 }

src/main/java/me/bobert/netneutrality/core/context/Context.java

@@ -5,16 +5,19 @@ package me.bobert.netneutrality.core.context;
  * https://discord.gg/qUa6zNFZsd
  */
 
-import me.bobert.netneutrality.context.AsyncContext;
+import me.bobert.netneutrality.shared.util.ContextUtils;
-import me.bobert.netneutrality.utils.ContextUtils;
 import net.dv8tion.jda.api.JDA;
-import net.dv8tion.jda.api.entities.*;
+import net.dv8tion.jda.api.components.MessageTopLevelComponent;
+import net.dv8tion.jda.api.entities.Guild;
+import net.dv8tion.jda.api.entities.Member;
+import net.dv8tion.jda.api.entities.Message;
+import net.dv8tion.jda.api.entities.MessageEmbed;
+import net.dv8tion.jda.api.entities.User;
 import net.dv8tion.jda.api.entities.channel.ChannelType;
 import net.dv8tion.jda.api.entities.channel.middleman.MessageChannel;
 import net.dv8tion.jda.api.events.Event;
 import net.dv8tion.jda.api.interactions.InteractionHook;
-import net.dv8tion.jda.api.interactions.components.LayoutComponent;
+import net.dv8tion.jda.api.modals.Modal;
-import net.dv8tion.jda.api.interactions.modals.Modal;
 import net.dv8tion.jda.api.utils.messages.MessageCreateData;
 import net.dv8tion.jda.api.utils.messages.MessageEditData;
 
@@ -48,7 +51,7 @@ public interface Context {
 
     void reply(Modal modal);
 
-    void reply(MessageCreateData messageCreateData, boolean ephemeral, List<LayoutComponent> components, Consumer<AsyncContext> consumer);
+    void reply(MessageCreateData messageCreateData, boolean ephemeral, List<MessageTopLevelComponent> components, Consumer<AsyncContext> consumer);
 
     void defer(boolean ephemeral, Consumer<AsyncContext> consumer);
 
@@ -66,7 +69,7 @@ public interface Context {
         reply(messageCreateData, false, List.of(), asyncMessage -> {});
     }
 
-    default void reply(MessageCreateData messageCreateData, List<LayoutComponent> components) {
+    default void reply(MessageCreateData messageCreateData, List<MessageTopLevelComponent> components) {
         reply(messageCreateData, false, components, asyncMessage -> {});
     }
 
@@ -90,7 +93,7 @@ public interface Context {
         reply(MessageCreateData.fromEmbeds(embeds));
     }
 
-    default void edit(MessageEditData messageEditData, boolean ephemeral, List<LayoutComponent> components, Consumer<AsyncContext> consumer) {
+    default void edit(MessageEditData messageEditData, boolean ephemeral, List<MessageTopLevelComponent> components, Consumer<AsyncContext> consumer) {
         if (isAcknowledged() && getInteractionHook() != null) {
             getInteractionHook().editOriginal(messageEditData).setComponents(components).queue(message1 -> consumer.accept(new AsyncContext(message1)));
             return;
@@ -99,7 +102,7 @@ public interface Context {
         reply(MessageCreateData.fromEditData(messageEditData), ephemeral, components, consumer);
     }
 
-    default void edit(MessageEditData messageEditData, List<LayoutComponent> components) {
+    default void edit(MessageEditData messageEditData, List<MessageTopLevelComponent> components) {
         edit(messageEditData, false, components, asyncMessage -> {});
     }
 
@@ -115,11 +118,11 @@ public interface Context {
         edit(List.of(embed), List.of());
     }
 
-    default void edit(List<MessageEmbed> embeds, List<LayoutComponent> components) {
+    default void edit(List<MessageEmbed> embeds, List<MessageTopLevelComponent> components) {
         edit(MessageEditData.fromEmbeds(embeds), components);
     }
 
-    default void edit(MessageEmbed embed, List<LayoutComponent> components) {
+    default void edit(MessageEmbed embed, List<MessageTopLevelComponent> components) {
         edit(List.of(embed), components);
     }
 
@@ -135,7 +138,7 @@ public interface Context {
         defer(false, consumer);
     }
 
-    default void replyEphemeral(MessageCreateData messageCreateData, List<LayoutComponent> components) {
+    default void replyEphemeral(MessageCreateData messageCreateData, List<MessageTopLevelComponent> components) {
         reply(messageCreateData, true, components, asyncMessage -> {});
     }
 
@@ -147,7 +150,11 @@ public interface Context {
         replyEphemeralWithLimit(message);
     }
 
-    default void replyEphemeral(String message, List<LayoutComponent> components) {
+    default void replyEphemeral(String message, MessageTopLevelComponent component) {
+        replyEphemeral(message, List.of(component));
+    }
+
+    default void replyEphemeral(String message, List<MessageTopLevelComponent> components) {
         replyEphemeral(MessageCreateData.fromContent(message), components);
     }
 
@@ -155,20 +162,20 @@ public interface Context {
         replyEphemeral(MessageCreateData.fromEmbeds(embeds));
     }
 
-    default void sendMessageInPrivate(MessageCreateData messageCreateData, List<LayoutComponent> components, Consumer<AsyncContext> consumer) {
+    default void sendMessageInPrivate(MessageCreateData messageCreateData, List<MessageTopLevelComponent> components, Consumer<AsyncContext> consumer) {
         User user = getDiscordUser();
         if (user != null) {
             user.openPrivateChannel()
-                    .flatMap(channel -> channel.sendMessage(messageCreateData).setComponents(components))
+                .flatMap(channel -> channel.sendMessage(messageCreateData).setComponents(components))
-                    .queue(message -> consumer.accept(new AsyncContext(message)));
+                .queue(message -> consumer.accept(new AsyncContext(message)));
         }
     }
 
-    default void sendMessageInPrivate(String message, List<LayoutComponent> components, Consumer<AsyncContext> consumer) {
+    default void sendMessageInPrivate(String message, List<MessageTopLevelComponent> components, Consumer<AsyncContext> consumer) {
         sendMessageInPrivate(MessageCreateData.fromContent(message), components, consumer);
     }
 
-    default void sendMessageInPrivate(MessageCreateData messageCreateData, List<LayoutComponent> components) {
+    default void sendMessageInPrivate(MessageCreateData messageCreateData, List<MessageTopLevelComponent> components) {
         sendMessageInPrivate(messageCreateData, components, asyncContext -> {});
     }