feat(bot): /bulk-kick — proof-of-pattern for the bulk-* command family

[LucasSantana-Dev]

Refs #1765 (the first proof-of-pattern command; the rest of the family — bulk-ban/warn/add-role/remove-role/purge — follow this template in later PRs).

What

A /bulk-kick role:@X reason: command that kicks every non-bot member holding a role, via the existing batch-job infra. Targeting is role-based (confirmed design — the existing message-oriented ScopeConfig doesn't cover member selection).

How (reuses the 90%-built batch infra)

• BulkKickExecutor — mirrors channelMoveExecutor's cursor/cancellation/pause contract. Non-bot role members sorted by id; cursor = last-kicked id (resumes cleanly after a restart). member.kickable guard; Discord codes 10007/50013 → skip, other errors → failed.
• /bulk-kick command — checkBatchPermissions('bulk_kick') (matrix entry already existed) → showBatchConfirmation (destructive gate, with a dry_run) → batchJobService.create (options:{roleId,reason}) → enqueueBatchJob. One registry line in batchJobWorker.ts.
• Estimation is exact (role.members.size, no message sampling) — so it inherently avoids the fix(bot): bulk-move-messages fetch limit 500 exceeds Discord's 100-message cap #1763 100-item-fetch trap the spec warned against copying.

Verify

• 5 executor tests (kick non-bot/skip bots, non-kickable skip, error-code classification, mid-run cancellation) — all pass
• type:check 0, eslint 0 (execute refactored into resolveKickTargets/kickMember/summary to stay under the complexity ceiling)

Safety

Destructive by design; gated behind KickMembers default-member-permission + the confirmation dialog + dry_run. Owner/higher-role members are skipped (kickable).

---

Summary by cubic

Adds a new /bulk-kick command that kicks all non-bot members with a selected role via the batch job system. Crash-safe, resumable, and pause/cancel-aware; first template for the bulk-* family and meets core requirements of #1765.

• New Features

  • Slash command: role, reason, dry_run; requires KickMembers; confirmation; exact target count; ETA.
  • BulkKickExecutor: ID-sorted targets; resumes via cursor; skips bots and non-kickable; treats Discord 10007/50013 as skip; logs other errors; emits progress with nextCursor; pauses if the client disconnects.
  • Batch worker lazily imports and registers the executor.

• Bug Fixes

  • Checkpoint nextCursor before kicks and restore tallies on resume.
  • Worker marks jobs as cancelled or paused instead of completed.
  • Command reports queueing failures when Redis is unavailable.

^{Written for commit 353aa33. Summary will update on new commits.}

Summary by CodeRabbit

• New Features

  • Added a bulk-kick moderation command to remove non-bot members with a selected role.
  • Added dry-run support, member counts, confirmation prompts, progress tracking, and cancellation handling.
  • Jobs pause safely when the bot is unavailable and resume from their last progress point.

• Bug Fixes

  • Members who cannot be kicked or are no longer available are skipped without stopping the entire operation.

• Tests

  • Added coverage for validation, filtering, error handling, cancellation, and kick outcomes.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a bulk-kick Discord command that creates batch jobs for eligible role members, implements resumable kicking with progress and cancellation handling, and registers the executor in the batch worker with Jest coverage.

Changes

Bulk kick moderation

Layer / File(s)	Summary
Bulk kick execution packages/bot/src/functions/moderation/batch/bulkKickExecutor.ts, packages/bot/src/functions/moderation/batch/bulkKickExecutor.spec.ts	Implements target resolution, ordered resumable processing, kick outcome classification, progress updates, cancellation, pausing, and tests for validation and error handling.
Bulk-kick command flow packages/bot/src/functions/moderation/commands/bulkKick.ts	Adds the slash command, permission checks, target counting, dry-run handling, confirmation, batch-job creation, enqueueing, and failure responses.
Worker registration packages/bot/src/workers/batchJobWorker.ts, packages/bot/src/workers/batchJobWorker.spec.ts	Registers BulkKickExecutor and adds the corresponding worker test mock.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related issues

• feat(bot): generalize bulk actions into a /bulk-* command family #1765 — Directly covers the /bulk-kick command, executor, and worker registration added here.

Possibly related PRs

• LucasSantana-Dev/Lucky#1564 — Extends the same batch-worker executor registration flow.

Suggested labels: enhancement

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the new /bulk-kick command as a proof-of-pattern for the bulk-* command family.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/1765-bulk-command-family

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Failed to generate code suggestions for PR

[github-actions]

	Warnings
⚠️	Big PR — 960 lines changed across 6 files. Consider splitting into smaller, reviewable chunks.
⚠️	User-facing change without a CHANGELOG.md update. Add a line under ## [Unreleased] if this should appear in release notes. (Or apply the skip-changelog label if this PR does not affect end users.)

Generated by 🚫 dangerJS against 353aa33

[cubic-dev-ai]

All reported issues were addressed

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

packages/bot/src/functions/moderation/batch/bulkKickExecutor.spec.ts (1)

70-122: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add regression coverage for checkpoint ordering and resume state.

These tests pass jest.fn() as onProgress, so they do not verify that the callback is awaited before member.kick(). They also lack a resumed-job fixture with non-zero persisted counters, allowing both resumability regressions to pass unnoticed.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/bot/src/functions/moderation/batch/bulkKickExecutor.spec.ts` around
lines 70 - 122, Extend the BulkKickExecutor tests around execute to verify
checkpoint ordering: use an onProgress callback that pauses, assert member.kick
is not called until it resolves, then continue and assert the kick occurs. Add a
resumed-job fixture with non-zero persisted progress/counters and assert
execution starts after the checkpoint while preserving those counters and
producing the correct final result.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/bot/src/functions/moderation/batch/bulkKickExecutor.ts`:
- Around line 78-90: The bulk kick flow must checkpoint each member before
performing the destructive action. In the batch execution method around
kickMember and onProgress, await onProgress with the current member cursor
before calling kickMember, then update tally and report post-action progress as
required by the existing BatchJobExecutor protocol, preserving accurate
processed, failed, skipped, and nextCursor values.
- Around line 54-66: The resumed batch execution must preserve previously
persisted outcome totals instead of resetting them. Update the tally
initialization in the executor flow around getById and resolveKickTargets to
seed kicked, skipped, and failed from the corresponding dbJob progress fields,
defaulting missing values to zero, so checkpoint() and the final summary remain
cumulative.

In `@packages/bot/src/functions/moderation/commands/bulkKick.ts`:
- Around line 124-139: The bulk kick command must handle a null result from
enqueueBatchJob before reporting success. Capture the enqueue result after
creating the job, and when enqueueing fails, transition the created job to the
existing retryable or failed state using the batch job service, then return an
error response instead of calling the success editReply; preserve the current
success path when enqueueing succeeds.
- Around line 29-33: Add preflight validation for the optional reason in the
bulk kick command before enqueueing any members, limiting its URL-encoded UTF-8
length to Discord’s 512-character audit-log maximum. Reject the command with an
appropriate user-facing error when exceeded, and preserve the existing
member.kick(reason) behavior for valid or absent reasons.

---

Nitpick comments:
In `@packages/bot/src/functions/moderation/batch/bulkKickExecutor.spec.ts`:
- Around line 70-122: Extend the BulkKickExecutor tests around execute to verify
checkpoint ordering: use an onProgress callback that pauses, assert member.kick
is not called until it resolves, then continue and assert the kick occurs. Add a
resumed-job fixture with non-zero persisted progress/counters and assert
execution starts after the checkpoint while preserving those counters and
producing the correct final result.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 12ca8ed7-ecd2-4800-a874-5a0461d58a37

📥 Commits

Reviewing files that changed from the base of the PR and between 65e2ff7 and 0457f2b.

📒 Files selected for processing (5)

• packages/bot/src/functions/moderation/batch/bulkKickExecutor.spec.ts
• packages/bot/src/functions/moderation/batch/bulkKickExecutor.ts
• packages/bot/src/functions/moderation/commands/bulkKick.ts
• packages/bot/src/workers/batchJobWorker.spec.ts
• packages/bot/src/workers/batchJobWorker.ts

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

<sub>Requires human review: Auto-approval blocked by 4 unresolved issues from previous reviews.

Re-trigger cubic</sub>

[LucasSantana-Dev]

Review dispositions (commit 75376fa7, independently re-verified: bot tsc 0, eslint clean on changed files, jest bulkKick batchJobWorker 21/21):

• P1 enqueue-null → false 'queued' (bulkKick.ts): ✅ FIXED — check enqueueBatchJob result; report failure (Redis unavailable) instead of claiming queued.
• P1 checkpoint after destructive kick (bulkKickExecutor): ✅ FIXED — checkpoint the cursor BEFORE kickMember(), so a crash never re-kicks on resume (skip-not-double-kick trade-off).
• P1 cancel recorded as completed: ✅ FIXED — worker now branches markCancelled / markPaused / markCompleted on the executor summary.
• P2 resume loses progress: ✅ FIXED — tally initialised from prior processed/failed/skipped counts on resume.
• P3 permission preflight bypass: Verified false positive — the bot Kick-Members check is present + correct.
  Added bulkKickExecutor.spec.ts covering checkpoint-before-kick + cancel-state.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud