discord-purge-bot

# Discord Purge Bot

Run controlled cleanup in Discord guild channels with safety gates and audit-friendly outputs.

## Safety Contract

- Use only a bot token (`DISCORD_BOT_TOKEN` or `--token`).
- Refuse user-account token flows and self-bot behavior.
- Run `purge-preview.mjs` first for every destructive request.
- Require explicit confirmation code before running deletion.
- Abort if channel is not a guild channel.
- Keep logs and JSON summaries for each run.

## Workflow

1. Collect scope: `channel-id`, optional `author-id`, `contains`, `regex`, `after`, `before`.
2. Read `references/discord-limits.md` before deletion runs.
3. Run preview to estimate impact and get confirm code.
4. Run deletion with confirm code.
5. Share summary: scanned, matched, deleted, failed, old-vs-recent split.

## Commands

### Preview

```bash
node scripts/purge-preview.mjs \
  --channel-id 123456789012345678 \
  --author-id 987654321098765432 \
  --contains "error" \
  --after "2026-03-01T00:00:00Z" \
  --max-scan 5000 \
  --out ./tmp/purge-preview.json
```

### Run Purge

```bash
node scripts/purge-runner.mjs \
  --channel-id 123456789012345678 \
  --author-id 987654321098765432 \
  --contains "error" \
  --after "2026-03-01T00:00:00Z" \
  --confirm "PURGE-XXXXXXXX" \
  --state-file ./tmp/purge-state.json \
  --out ./tmp/purge-result.json
```

### Dry Run

```bash
node scripts/purge-runner.mjs --channel-id 123456789012345678 --confirm "PURGE-XXXXXXXX" --dry-run
```

### Clone or Nuke Channel

```bash
node scripts/purge-nuke.mjs --channel-id 123456789012345678 --confirm "NUKE-XXXXXXXX" --out ./tmp/nuke.json
node scripts/purge-nuke.mjs --channel-id 123456789012345678 --confirm "NUKE-XXXXXXXX" --delete-old --out ./tmp/nuke.json
```

## Script Roles

- `scripts/purge-preview.mjs`: scan channel messages, apply filters, return counts and confirm code.
- `scripts/purge-runner.mjs`: execute deletion with 2-week split (`bulk-delete` + single delete fallback).
- `scripts/purge-nuke.mjs`: create...

# discord-purge-bot

OpenClaw skill for controlled Discord message cleanup with preview, guarded execution, and audit-friendly output.

## Usage
See `SKILL.md` for workflow and commands.